# Team collaboration: shared context and rules

URL: https://developertoolkit.ai/en/teams/adopt/team-collaboration/
Description: Give every engineer's Claude Code, Codex or Cursor agent the same team context: shared rules, a review-to-rule loop, committed plans and proof they loaded.

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](/en/cto-scorecard-guide/shared-agent-rules/). 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](/en/cto-scorecard-guide/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:

**Claude Code**

- **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` and `stable` channels since `stable` reached v2.1.287, checked 2026-10-12). Older builds read `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.

**Codex**

- **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.

**Cursor**

- **Shared:** Cursor applies project instructions through **Rules** ([cursor.com/docs/rules](https://cursor.com/docs/rules), checked 2026-10-12): project rules are `.mdc` files in `.cursor/rules`, and Cursor also supports `AGENTS.md` in the project root and in subdirectories. Cursor reads `AGENTS.md` and `CLAUDE.md` directly, so it needs no Rules copy; add a rule in `.cursor/rules` only for Cursor-only lines, and follow the Rules page for syntax.
- **Do not** paste the core into a Cursor rule or generate a Rules copy of it. Cursor already reads the file, and a second copy repeats it and 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](/en/cto-scorecard-guide/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.

1. **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.

2. **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.

3. **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](/en/cto-scorecard-guide/shared-agent-rules/) in the same pull request.

4. **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.

**Copy-paste prompt: draft the shared core from existing code**

```text
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 (Team and Enterprise; generally available per Anthropic, checked 2026-10-16) is tuned by `CLAUDE.md` and a repository-root `REVIEW.md` of review-only instructions. [Agent PR review](/en/workflows/ship/agent-pr-review/) covers how to set those up.

**Copy-paste prompt: codify a settled review decision**

```text
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](/en/method/lifecycle/artifact-chain/) and [spec-driven development](/en/workflows/plan/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.

**Copy-paste prompt: write a handoff note a teammate's agent can use**

```text
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.

**Copy-paste prompt: new-engineer orientation**

```text
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](/en/cto-scorecard-guide/dev-onboarding-time/) 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.

**Claude Code**

- **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 stopped answering in channels of Claude-paired workspaces on 2026-10-05 (direct messages are unaffected); it remains the path on Pro and Max only in workspaces that no organization has connected to Claude Tag. See [Claude Tag](/en/claude-code/team/claude-tag/).
- **Review:** managed Code Review posts inline pull request comments (Team and Enterprise; generally available per Anthropic, checked 2026-10-16; not available with Zero Data Retention).

**Codex**

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 `@ChatGPT` with a prompt; with Cloud delegation enabled in your workspace, ChatGPT sends repository work to a Codex Cloud task and returns the result to the thread (OpenAI's docs, checked 2026-10-12).
- **Linear:** assign an issue to Codex or mention `@Codex` in a comment.

**Cursor**

Verified on 2026-08-28; cursor.com could not be reached on 2026-09-26.

- **Automations** run Cloud Agents on a schedule or in response to events from GitHub, GitLab, Slack, webhooks, Linear and more.
- **Bugbot** reviews pull requests for bugs, security issues and code quality problems. See [Bugbot](/en/cursor-ide/ship/bugbot/).

A channel agent acts under a shared identity with access to your repositories. Decide which repositories and data it may read before you connect it ([privacy and data handling](/en/org/privacy-data-handling/)), and never let an agent act on a fork's pull request while secrets are in its environment: a contributor's `AGENTS.md` is instructions the agent will follow.

## 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:

1. **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.
2. **A load check on rule changes.** The CI check and fresh-session probe on [shared agent rules](/en/cto-scorecard-guide/shared-agent-rules/) prove each tool loaded the current core. Run them on every rule change and after every tool upgrade.
3. **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.

**Copy-paste prompt: check a diff against the team rules**

```text
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`):

```bash
# 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](/en/teams/trust-transfer/) 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, a build older than v2.1.277, 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` in Claude Code or `codex debug prompt-input` in Codex.

**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](/en/workflows/context/pruning-context-files/) 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](/en/cto-scorecard-guide/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](/en/workflows/harness/agent-ready-codebase/). Next, set up the tested file layout in [shared agent rules](/en/cto-scorecard-guide/shared-agent-rules/), then move on to reviewing agent work without reading every line. Tool-specific setup: [Claude Code team collaboration](/en/claude-code/team/team-collaboration/) and [Cursor team collaboration](/en/cursor-ide/team/team-collaboration/).

- [Shared agent rules](/en/cto-scorecard-guide/shared-agent-rules/) — One AGENTS.md core, thin adapters, a CI check and a probe per tool.
- [AGENTS.md and CLAUDE.md content](/en/developer-scorecard-guide/claude-md-context/) — What earns a line in the core, and what to leave out.
- [Shared skills](/en/cto-scorecard-guide/shared-skills/) — Package team procedures that load on demand, not in every session.
- [Agent PR review](/en/workflows/ship/agent-pr-review/) — Set up review agents that read the same team rules.
- [Team onboarding and adoption](/en/teams/adopt/team-adoption/) — Roll the shared workflow out to the whole team.
- [Helping the team stop reading every diff](/en/teams/trust-transfer/) — Move review from lines to evidence.
