Team collaboration: shared context and rules

Team collaboration with AI coding agents means the team, not each engineer, owns the context every agent works from: one committed AGENTS.md core with thin tool adapters, code-review decisions turned into rules, and plans committed next to the code. A shared rule counts only when a CI check or a fresh-session probe proves each agent loaded it.

Two engineers on your team ask their agents for a new API endpoint on the same morning. One gets a handler wrapped in your asyncHandler() that throws AppError; the other gets a bare async function that throws raw errors, in a different folder. The pull request turns into 30 comments about conventions, and none of them is about whether the endpoint works. This page is for the tech lead who wants those conventions to live in the repository, where every agent reads them, instead of in review comments that nobody reads twice.

What your team gets from shared agent context

A map of what belongs in shared context, what stays personal, and where each lives for Claude Code, Codex and Cursor.
A prompt that drafts the shared core from the code you already have, so nobody starts from a blank file.
A review-to-rule loop that turns each settled review argument into a rule in the same pull request.
A convention for committing plans and handoff notes, so a teammate’s agent can pick up work in progress.
A conformance check that shows whether a diff follows the rules without a human reading every line.
The failure modes that make shared context silently stop working, with a recovery for each.

The file mechanics (discovery order, adapters, the CI check, precedence) live on the canonical page, shared agent rules: one core, tested adapters. This page covers how a team works with that context day to day.

What belongs in shared context, and what stays personal?

Shared context is anything a teammate’s agent needs to produce code your reviewers accept. Personal context is anything that only makes one engineer faster. Mixing the two is the most common reason shared rules rot: a personal preference committed to the core becomes a rule nobody agreed to.

Context	Shared or personal	Where it lives	Who changes it
Commands, definition of done, protected paths, human gates	Shared	root `AGENTS.md`	the harness owner, through a pull request
Conventions for one package or risk area	Shared	that directory’s `AGENTS.md`	the package owner
Plans, specs and handoff notes for work in progress	Shared	`docs/plans/` in the repository	whoever owns the ticket
Repeatable procedures (release, migration, triage)	Shared, loaded on demand	a skill, see shared skills	the skill owner
Editor habits, verbosity, personal shortcuts	Personal	user-level settings, never committed	each engineer
What an agent learned in one engineer’s sessions	Personal until promoted	the tool’s memory	promoted to a rule by pull request

Where that maps to files differs per tool:

Shared: a committed CLAUDE.md whose first line is @AGENTS.md, followed only by Claude-specific lines. The import works on every version and release channel.
Direct AGENTS.md reading: Claude Code reads AGENTS.md itself, but only when the project has no CLAUDE.md: from v2.1.277 for first-party sessions and from v2.1.281 on Bedrock, Google Cloud, Foundry, LLM gateways and telemetry-off sessions (both on the latest channel on 2026-09-26). The stable channel (2.1.274) reads CLAUDE.md files only, and the “Project instructions” toggle in /config can switch direct reading off. The adapter covers every case.
Personal: CLAUDE.local.md (keep it gitignored) and auto memory, which Claude accumulates from your own sessions. When auto memory learns something the whole team needs, write it into AGENTS.md by pull request instead of hoping every teammate’s session learns it too.
Check what loaded: /context lists the memory files in the session.

Shared: the root AGENTS.md plus directory AGENTS.md files. Codex collects them from the project root down to the working directory, root first, up to project_doc_max_bytes (32 KiB by default). /init drafts a first AGENTS.md.
Do not commit AGENTS.override.md: Codex reads it instead of that directory’s AGENTS.md, and Claude Code ignores it, so the two tools diverge.
Personal: Codex memories are stable but off by default (checked against Codex 0.157.1 on 2026-09-26). If you turn them on, promote anything the team needs into AGENTS.md.
Trust: since 0.150.0, a project marked untrusted on a machine does not supply project-level AGENTS.md there.
Check what loaded: codex debug prompt-input "noop" prints the model-visible input.

Shared: Cursor applies project instructions through Rules (cursor.com/docs/rules, verified 2026-08-28). The current rule file format could not be re-verified on 2026-09-26, so follow the Rules page for syntax and keep the rule a pointer to AGENTS.md plus Cursor-only lines.
Do not paste the core into a Cursor rule. A copy drifts the first time someone edits AGENTS.md.
Personal: keep personal preferences out of committed rules.
Check what loaded: paste the fresh-session probe from shared agent rules into a new Agent chat after every Cursor update.

Draft the shared core from the code you already have

Write the core from the conventions your code actually follows, not from the wiki. The agent does the reading; the team makes the decisions.

Have the agent draft the core. Run the prompt below in Claude Code, Codex or Cursor from the repository root. In Codex, /init produces a first AGENTS.md too; the prompt adds the inconsistency list, which is the valuable part.
Settle every inconsistency in one meeting. The draft surfaces conflicts such as “two error-handling styles in src/api/”. Pick the canonical pattern for each and record the loser under “Do not”. Thirty minutes with the people who review most is enough.
Commit the core and the adapters in one pull request. The root AGENTS.md, a CLAUDE.md adapter, a Cursor pointer rule, and a CODEOWNERS entry for all three. Add the CI check from shared agent rules in the same pull request.
Tell the team what changed. One message: where the core lives, how to propose a rule, and that review comments about conventions now link to a rule or become one.

Draft a root AGENTS.md that captures this repository's real, current
conventions. Read enough to be accurate, not everything:
- 3-4 route handlers under src/api/ for endpoint and error-handling patterns
- 2-3 UI components for naming, file structure and state handling
- the test files next to those modules for test naming and structure
- package.json, tsconfig.json and the CI workflow for the real commands

Write these sections: Rules version (today's date + ".1"), Commands,
Project structure, Naming, Error handling, Testing, Definition of done,
Protected paths, Do not. Quote real file paths and helper names. Give each
rule a one-line "why". Stay under 150 lines.

Then, separately, list every place where the code follows two patterns
for the same thing, with two file paths per pattern, so the team can pick
the canonical one. Do not write any file; print the draft and the list.

Turn review comments into rules in the same pull request

The core stays accurate only if review feeds it. When a review thread settles a convention, the settlement goes into AGENTS.md in the pull request where it was settled. A rule left in a comment is lost on merge; a rule in the core reaches every agent on the next pull.

Three conventions keep the loop honest:

Every rule change cites its trigger: the review thread, incident or onboarding failure that prompted it. A rule nobody can justify is the first to delete when the file grows.
The harness owner approves every rule change through CODEOWNERS. Anyone may propose; one person keeps the core coherent.
A repeated convention comment is a bug report against the core. When a reviewer writes the same comment twice in a month, the second comment links to a new rule instead of explaining it again.

The rules also steer the review bots, so one edit changes both generation and review. Codex’s GitHub code review reads custom review rules from AGENTS.md (verified 2026-08-28). Claude Code’s managed Code Review (research preview, Team and Enterprise) is tuned by CLAUDE.md and a repository-root REVIEW.md of review-only instructions. Agent PR review covers how to set those up.

In code review on this branch we settled a convention: every repository
function that can return zero rows returns a typed Result from
src/lib/result.ts and handles the empty case explicitly. It never returns
null.

1. Add this to AGENTS.md under "Error handling" as one imperative bullet
   with a one-line "why" and a two-line before/after example.
2. If an existing rule contradicts it, show that rule and propose the
   edit; do not keep both.
3. List every current function under src/repositories/ that breaks the
   new rule, with file:line, so we can decide whether to fix them now.
Show the AGENTS.md diff and the list. Do not change any other file.

Commit plans and handoffs so a teammate’s agent can continue

Rules describe how the team writes code. Plans describe what the team is in the middle of. When a plan exists only in one engineer’s session, nobody else’s agent can continue the work, review it against intent, or notice that two people are solving the same problem.

Keep work-in-progress context in the repository:

One plan file per ticket in docs/plans/<ticket-id>.md, committed on the feature branch: goal, acceptance criteria, decisions made, open questions, and the verification command. The artifact chain and spec-driven development cover what a good plan and spec contain.
A handoff note before you stop, appended to the plan, whenever someone else (or you, next week) will pick the branch up. The agent writes it; you check it against the diff.
Delete or archive the plan on merge. A stale plan in docs/plans/ is context that misleads the next agent that reads it.

I am handing this branch to a teammate. Append a "Handoff" section to
docs/plans/PAY-412.md with:
1. What is done, citing the commits on this branch (git log main..HEAD).
2. What is not done, as a checklist in the order it should happen.
3. Decisions made in this session and the reason for each, including
   options we rejected.
4. The exact command that proves the work so far passes, and its current
   result (run it).
5. Anything surprising about the code that the next agent will trip on.
Only state what you can point to in the diff, the plan or the command
output. Mark anything you are unsure of as "unverified".

PAY-412 is the ticket ID; replace it with yours. The teammate starts their session with “Read docs/plans/PAY-412.md and continue from the Handoff checklist”, in any of the three tools.

Onboard a new engineer with the team’s context

A new hire’s first question is usually one the shared context already answers. Because the agent reads the committed core, its answers reflect your conventions, not generic advice, and each wrong answer shows you a gap in the core.

I am new to this codebase. Using AGENTS.md and the code itself, give me an
orientation, not a lecture:
1. The request lifecycle for an authenticated API call, from entry point
   to response, with the file for each step.
2. Our error-handling and validation conventions, with the helper names
   I should reuse.
3. The naming and folder pattern for a new feature module.
4. Which directories are generated, protected or off-limits.
Cite a file for every claim. End with a "first pull request checklist" of
the conventions reviewers will check. If AGENTS.md and the code disagree,
say so explicitly instead of choosing.

The last line matters most: every disagreement the orientation reports is a rule to fix. Developer onboarding: prove one safe workflow turns this into a measurable onboarding fixture.

Bring the agent into the channels the team already uses

When the agent answers in a shared channel instead of in one engineer’s terminal, the answer becomes team knowledge. A product manager asks in Slack how a feature behaves, the agent answers in the thread from the code, and everyone sees the same answer. These integrations read the same committed context, so they follow the same rules.

GitHub: anthropics/claude-code-action@v1 responds to @claude in issues and pull requests and can turn an issue into a pull request.
Slack: Claude Tag runs @Claude as your organisation’s shared identity with admin-configured access (Team and Enterprise). The earlier Claude Code Slack app remains the path on Pro and Max. See Claude Tag.
Review: managed Code Review posts inline pull request comments (research preview, Team and Enterprise, not available with Zero Data Retention).

Verified on 2026-08-28; OpenAI’s docs host could not be reached on 2026-09-26.

GitHub: request a review with @codex review or @codex security review, or enable automatic reviews; custom review rules come from AGENTS.md.
Slack: mention @Codex with a prompt; Codex creates a cloud chat and replies with the results.
Linear: assign an issue to Codex or mention @Codex in a comment.

How do you know every agent follows the shared rules?

Nobody on the team should verify conventions by reading every generated line. Use three layers, from cheapest to most expensive:

Deterministic gates first. Anything a linter, formatter, type checker or architecture test can enforce belongs there, not in AGENTS.md. A rule that a tool can check is a rule a model does not need to remember.
A load check on rule changes. The CI check and fresh-session probe on shared agent rules prove each tool loaded the current core. Run them on every rule change and after every tool upgrade.
A conformance review on each pull request. Before you request human review, have an agent check the diff against the core and nothing else. It returns violations with the rule quoted, so the human reviewer checks a short list instead of the whole diff.

Review only the changes on this branch against main: use the diff piped
to you, or run git diff main...HEAD if none was piped.
Check them against the rules in AGENTS.md and any AGENTS.md in the
directories the diff touches. Ignore style a formatter would fix.
For each violation output one line:
file:line | the rule, quoted verbatim | the smallest fix
If a change is not covered by any rule but looks like a new convention,
list it under "Candidate rules". If there are no violations, print
NO VIOLATIONS and nothing else. Do not edit any file.

Run it non-interactively from a trusted local checkout (the prompt file is the Aside above, saved as tests/agent-rules/conformance.txt):

# Terminal, repository root, on your own branch (not a fork's code).
# Claude Code: pipe the diff in; plan mode cannot edit files.
git diff main...HEAD | claude -p "$(cat tests/agent-rules/conformance.txt)" \
  --permission-mode plan --output-format text

# Codex: a read-only sandbox lets it run git diff but not write.
codex exec --sandbox read-only --ephemeral "$(cat tests/agent-rules/conformance.txt)"

codex review --base main runs Codex’s own review preset instead; in Codex 0.157.1 it does not accept custom instructions together with --base, so use codex exec for a rules-only check. In print mode, plan mode can end by presenting a plan instead of the report; if the output arrives wrapped as a plan, run Claude Code in default mode with --disallowedTools Edit Write instead (checked against claude --help, v2.1.283). In Cursor, paste the prompt into a new Agent chat on the branch.

Who signs off. The pull request author attaches the conformance output. The human reviewer checks the violations list, the candidate rules and the tests, not every line. The harness owner approves any candidate rule that becomes a real one. To see whether the loop works, count review comments tagged as conventions per merged pull request each month: the number should fall as the core absorbs them. Helping the team stop reading every diff covers the wider move.

What breaks when a team shares agent context?

The core drifts from the code. Symptom: agents follow a pattern the team abandoned months ago. Cause: rules were written once and never updated. Recovery: re-run the drafting prompt each quarter, diff its output against the committed core, and settle each difference in a pull request.

One engineer’s agent ignores the rules. Symptom: the same prompt produces conforming code for everyone but one person. Cause, in Claude Code: a CLAUDE.md anywhere Claude Code loads from, the stable channel, or “Project instructions” switched off in /config stops AGENTS.md from loading directly. In Codex: the project is marked untrusted on that machine. Recovery: the @AGENTS.md adapter fixes the Claude Code cases; mark the project trusted in Codex; confirm with /context or codex debug prompt-input.

Codex and Claude Code disagree in one directory. Symptom: behaviour differs by tool in one package only. Cause: a committed AGENTS.override.md, which Codex reads instead of that directory’s AGENTS.md and Claude Code ignores. Recovery: merge its content into AGENTS.md, delete it, and keep the CI check that fails on it.

The core grows until rules are lost. Symptom: a directory rule is missing from codex debug prompt-input, or agents follow early rules and forget late ones. Cause: the chain passed Codex’s 32 KiB default and was truncated, or the file is too long to steer well in any tool. Recovery: move procedures into skills, move checkable rules into linters, and use the pruning protocol to cut what does not change behaviour.

Rules without reasons get followed inconsistently. Symptom: the agent applies “use AppError” in handlers but not in background jobs. Cause: the rule states the what, not the why, so the model cannot generalise. Recovery: add a one-line reason to each rule; the drafting and codifying prompts above already ask for one.

A personal preference becomes a team rule. Symptom: the core contains rules nobody remembers agreeing to. Cause: someone committed their own habits. Recovery: every rule change cites its trigger, and the harness owner rejects rules without one.

A rule is treated as a security control. Symptom: an agent reads .env although the core says never to. Cause: instructions steer the model; they do not bind it. Recovery: enforce hard limits with permission rules, sandboxes, CI and branch protection, reviewed in shared hooks governance, and keep the sentence in the core only as an explanation of the control.

Where to go next with shared team context

Before this page, make the codebase agent-ready. Next, set up the tested file layout in shared agent rules, then move on to reviewing agent work without reading every line. Tool-specific setup: Claude Code team collaboration and Cursor team collaboration.

Shared agent rules One AGENTS.md core, thin adapters, a CI check and a probe per tool.

AGENTS.md and CLAUDE.md content What earns a line in the core, and what to leave out.

Shared skills Package team procedures that load on demand, not in every session.

Agent PR review Set up review agents that read the same team rules.

Team onboarding and adoption Roll the shared workflow out to the whole team.

Helping the team stop reading every diff Move review from lines to evidence.