AGENTS.md and CLAUDE.md — concise repository context

Repository context for coding agents is one short, versioned AGENTS.md that states the project layout, the exact build and test commands, the boundaries, and the proof required before work counts as done. Claude Code, Codex and Cursor discover instruction files differently, so a working setup also includes a check that shows which files each tool actually loaded.

You changed the test command from npm test to pnpm test:unit last sprint. CLAUDE.md got the edit, AGENTS.md did not, and today a Codex session ran the old command, saw it fail, and “fixed” the failure by rewriting a test. Nobody can say which file each agent read, because nobody ever checked.

This page is for the developer who owns a repository’s agent setup, and for the tech lead who scores it. It answers question 9 of the Developer Scorecard. Team-wide governance of the same files is the job of shared agent rules.

What a verified repository context gives you

A root AGENTS.md of about 40 lines that every agent and every new teammate can trust.
A one-line CLAUDE.md adapter and a Cursor fallback, with no copied policy to drift.
Path-scoped rules for the two or three directories that need them, and nothing else always loaded.
A 20-line script that fails when Codex stops loading your rules, plus the Claude Code views that show the same for Claude.
Four copy-paste prompts: draft the core from evidence, probe discovery, probe a scoped rule, and audit for drift.

What belongs in the root AGENTS.md, and what does not?

Put a line in the always-loaded core only when it is true for every task in the repository and an agent could not discover it by reading the code. Everything else goes to a layer that loads only when it is needed.

Content	Where it goes	Why
Layout, exact commands, boundaries, completion evidence	Root `AGENTS.md`	Every session needs it
Conventions for one directory (`src/billing/`, `infra/`)	Path-scoped rule or nested `AGENTS.md`	Loads only near that code
Multi-step procedures (release, migration, incident)	A skill	Loads on demand
“Never” rules that must hold	Hooks, permissions and sandboxing, CI, branch protection	Instructions steer; they do not enforce
Current task state	`intent.md`, `spec.md`, `plan.md` in the artifact chain	Expires when the task ends
Personal preferences	`~/.claude/CLAUDE.md`, `CLAUDE.local.md`, or your Codex user file	Not everyone’s truth

A core that fits this table looks like this, for a TypeScript monorepo on pnpm:

# Repository contract
<!-- Owner: @platform-team · reviewed monthly · last review 2026-09-26 -->

## Layout
- Web app: `apps/web/` (Next.js). API: `apps/api/` (Fastify). Shared code: `packages/`.
- Database migrations: `apps/api/migrations/`, one file per change, never edited after merge.

## Commands (run from the repository root)
- Install: `pnpm install --frozen-lockfile`
- Unit tests: `pnpm test:unit` · one package: `pnpm --filter @acme/api test:unit`
- Types: `pnpm typecheck` · Lint: `pnpm lint` · E2E: `pnpm test:e2e` (needs `pnpm dev` running)

## Boundaries
- Do not run commands that reach production, and do not read `.env.production`.
- Ask before adding a dependency or changing an exported API in `packages/`.

## Done means
- `pnpm typecheck`, `pnpm lint` and `pnpm test:unit` pass; report the commands and their results.
- List changed files and anything you could not verify.

Every line names a path, a command or a checkable condition. “Write clean code” and “test thoroughly” fail that test: no reviewer and no agent can tell whether they were followed. Anthropic’s memory documentation gives the same advice (“Run npm test before committing” instead of “Test your changes”) and a size target of under 200 lines per CLAUDE.md file (Claude Code memory docs, checked 2026-09-26).

How do Claude Code, Codex and Cursor find the core?

The three tools discover instruction files differently, so the adapter differs per tool. Keep the policy in AGENTS.md and give each tool the thinnest adapter that makes it load that file.

Claude Code reads CLAUDE.md or .claude/CLAUDE.md from the working directory and every directory above it at launch, and nested CLAUDE.md files when it reads files in their directory. Since v2.1.277 it also reads AGENTS.md directly, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. The stable npm channel reached v2.1.280 on 2026-09-30, so a teammate on an older stable build does not get the direct read yet.

Use an import, which works on both channels and never loads the file twice:

@AGENTS.md

## Claude Code only
- Use plan mode before changing anything under `apps/api/migrations/`.

Scoped detail goes in .claude/rules/*.md. A rule with paths frontmatter loads only when Claude reads a matching file; paths is the only frontmatter key Claude Code reads there (checked in Claude Code v2.1.285 on 2026-09-30).

---
paths:
  - "apps/api/src/billing/**"
---
- Money is integer cents (`number`), never floats. Use `formatCents()` for display.
- Every billing change needs a test in `apps/api/test/billing/`.

.claude/rules/ is Claude-only: Codex never reads it. And with the @AGENTS.md import in place, Claude Code does not load a nested AGENTS.md either, because its default “Project instructions” mode (claude-md-or-agents-md) uses AGENTS.md only in a project that has no CLAUDE.md of its own. So put a scoped rule that both tools must follow in the nested AGENTS.md, and give Claude a nested CLAUDE.md beside it that contains only @AGENTS.md; Claude loads it when it reads a file in that directory:

@AGENTS.md

The alternative is to set “Project instructions” in /config to claude-md-and-agents-md, which loads AGENTS.md files beside CLAUDE.md and skips a file that CLAUDE.md already imports (checked in Claude Code v2.1.285 on 2026-09-30). Keep .claude/rules/*.md for scoped detail that only Claude needs.

Two details from the memory docs matter here: imports organise a long file but do not reduce its context cost, because imported files load at launch, and block-level HTML comments are stripped before the content reaches the model, so the owner line in the template above costs no tokens.

Codex needs no adapter: it reads AGENTS.md natively. Checked against codex-cli 0.157.1 (source codex-rs/core/src/agents_md.rs and local runs on 2026-09-26), it:

finds the project root by walking up to the nearest .git (configurable with project_root_markers),
loads one file per directory from that root down to the directory you started in, root first,
prefers AGENTS.override.md over AGENTS.md in the same directory, and accepts extra names listed in project_doc_fallback_filenames,
stops at a combined budget of project_doc_max_bytes, 32 KiB by default, and truncates the rest without telling you,
skips project AGENTS.md files entirely in an untrusted project (since 0.150.0).

Scoped detail goes in a nested AGENTS.md, for example apps/api/src/billing/AGENTS.md. Codex preloads it only when you start the session in that directory or below it; started from the root, the agent sees it only if it opens the file. Codex’s .rules files are a different thing: they decide which commands may run outside the sandbox, and they carry no instructions.

Cursor applies instructions through Rules (cursor.com/docs/rules, verified 2026-08-28). Project rules live in .cursor/rules/, the directory Claude Code’s /init also reads when it drafts CLAUDE.md. cursor.com was unreachable from our verification environment on 2026-09-26, so the current rule file format and whether your Cursor build loads a root instruction file on its own are not verified here.

Adapter: run the discovery probe from the next section in a new Agent chat. If the answer quotes your core, add nothing. If it does not, add one always-applied project rule that tells the agent to read the core before any work, in the format the Rules page specifies today, and keep only Cursor-specific lines in it.
Scoped detail: a project rule scoped to a file pattern, again in the documented format.
Generated option: if you maintain many rules across tools, generate .cursor/rules/ from one source with rulesync, as shown in one rules source for every agent.

Repeat the probe after every Cursor update, because a pointer rule depends on the model choosing to open the file.

Build the context in six steps

Draft from evidence, not memory. Run /init in Claude Code or Codex for a first draft, or paste the drafting prompt below. In Claude Code, /init also reads existing .cursor/rules/, .cursorrules and .github/copilot-instructions.md and folds their important parts into the draft, and suggests improvements when a CLAUDE.md already exists instead of overwriting it.
Cut every line that fails the table above. Delete anything the agent can read from package.json, the directory tree or the linter config. Delete adjectives. Keep commands, paths and boundaries.
Run every command in the file in a clean checkout. A command that has not run successfully does not go in the core. This is also the moment to find the pnpm test:e2e that silently needs a dev server.
Move scoped detail out. For each directory that has real local conventions, write one nested AGENTS.md and a one-line CLAUDE.md beside it that imports it, as the Claude Code tab shows. Use a .claude/rules/<topic>.md with paths only for detail that Claude alone needs. Two or three scoped files are typical; twenty means the core is being split rather than trimmed.
Wire the adapters from the tabs above: CLAUDE.md with @AGENTS.md, nothing for Codex, a probe and possibly a pointer rule for Cursor.
Assign an owner and a gate. Add AGENTS.md, CLAUDE.md, .claude/rules/ and .cursor/rules/ to CODEOWNERS, and run the load check from the next section in CI (pinned CLI, see the Codex tab). The owner signs off on every change to the core, the same way they would on a CI config change.

Draft a root AGENTS.md for this repository. Use only facts you can verify here:
1. Read package.json (or the build manifest), the CI workflow files, the README and the top two directory levels.
2. For every build, test, lint and typecheck command you propose, run it once and record the exit code. Leave out any command that failed and tell me why.
3. Sections: Layout, Commands, Boundaries, Done means. Maximum 50 lines.
4. Do not include anything a reader can infer from the code (framework names in package.json, file naming the linter already enforces).
5. Do not write the file. Show the draft, then list each command with its exit code.

How do you prove each agent loaded the rules?

Two kinds of proof work without anyone reading the files line by line: a load check that shows which files reached the model, and a behaviour probe that shows the agent can state and apply them.

Load check, per tool.

Run /context in a new session and check the list under Memory files; /memory lists the same files and opens them. For a record you can inspect later, log every load with an InstructionsLoaded hook in your personal .claude/settings.local.json (the command needs jq):

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{file_path, load_reason}' >> \"$CLAUDE_PROJECT_DIR/.claude/instructions-loaded.log\""
          }
        ]
      }
    ]
  }
}

Open a file under apps/api/src/billing/ and the log gains a path_glob_match line for billing.md. The hook fires for CLAUDE.md, rules and imports (load_reason: "include"). The log may not show an AGENTS.md that Claude reads directly without a CLAUDE.md, because that path runs through the built-in agents-md plugin; the import makes the load visible. The hook is observability only; it cannot block a load. Add the log file to .gitignore.

/doctor prompt-audit (checked in Claude Code v2.1.285 on 2026-09-30) audits the instruction files that load in this project. It runs through the bundled claude-api skill, so it is unavailable when bundled skills are disabled in settings. Review its findings before you accept any fix.

codex debug prompt-input prints the model-visible prompt as JSON without calling a model (no login needed, checked on codex-cli 0.157.1). That makes the load check scriptable:

#!/usr/bin/env bash
# Fails when Codex stops loading a rule you depend on. Run from the repository root.
set -euo pipefail

expect() {  # expect <directory> <string that must reach the model>
  if ! (cd "$1" && codex debug prompt-input) | grep -F -- "$2" >/dev/null; then
    echo "FAIL: '$2' not loaded when Codex starts in $1" >&2
    exit 1
  fi
}

expect .                     'pnpm test:unit'
expect apps/api/src/billing  'integer cents'
echo "Codex loads the expected instructions."

The billing line assumes the rule lives in apps/api/src/billing/AGENTS.md, as step 4 recommends; Codex never reads .claude/rules/.

The script catches the three silent Codex failures at once: the 32 KiB truncation, an AGENTS.override.md that shadows the real file, and a nested file that no longer loads. Run it in a pull_request job with no secrets in the environment; it reads the contributor’s files and needs none. Install a pinned CLI in the job: npm install -g @openai/codex@0.157.1, and bump the pin deliberately, because a newer Codex can change what the check reports.

Behaviour probe, in every tool. Paste these into a fresh session after any change to the instruction files. The expected answers go in the pull request description; a wrong answer blocks the merge.

Before editing anything, answer from your loaded instructions only, not by searching the repository:
1. Which instruction files did you load at session start? Give their paths.
2. What are the exact commands to run unit tests, typecheck and lint?
3. Which actions are you told not to take?
4. What must you report before you call a task done?
If you have no instruction for one of these, say "none loaded" instead of guessing.

Open apps/api/src/billing/invoice.ts and read it without editing. Then tell me:
1. Which repository-wide instructions and which billing-specific instructions apply to this file, with the path of each source file.
2. How you would represent 19.99 EUR in this code, and why.
If no billing-specific instruction loaded, say so explicitly.

The second question is the useful one: an agent that answers “integer cents, 1999” has applied the rule, not only listed it.

When should a rule be added, and when deleted?

Add a line only after the same mistake happens twice in separate sessions, and only when you can phrase the fix as something checkable. That is the “two-strike” part of the top Scorecard answer. The other half is deletion: a rule that no probe or failure has needed in months is context you pay for in every session. The ablation protocol for pruning context files removes lines one at a time and restores only what breaks.

Audit every instruction file that applies in this repository: AGENTS.md at any depth, AGENTS.override.md, CLAUDE.md, CLAUDE.local.md, .claude/rules/, .cursor/rules/.
For each rule, report one of: DUPLICATE (same rule in two files), CONFLICT (two files disagree), STALE (names a path, script or command that does not exist; check each one), VAGUE (cannot be verified), or OK.
Then propose the smallest patch that leaves the policy in AGENTS.md only and the tool files as adapters. Do not edit runtime code, and do not apply the patch.

What breaks with AGENTS.md and CLAUDE.md, and how do you recover?

Symptom	Cause	Recovery
Claude Code ignores `AGENTS.md` after you add a personal `CLAUDE.local.md`	Any `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` stops the direct `AGENTS.md` read	Add `@AGENTS.md` to a `CLAUDE.md`, or set Project instructions in `/config` to `claude-md-and-agents-md`
A teammate’s Claude Code never sees `AGENTS.md`	They are on a build before v2.1.277 (the `stable` channel reached v2.1.280 on 2026-09-30), a Bedrock, Google Cloud, Microsoft Foundry, LLM-gateway or telemetry-off session before v2.1.281, or the built-in `agents-md` plugin is off	The `@AGENTS.md` import works on every version
Codex follows the root rules but not the ones at the end of a nested file	The combined files exceed `project_doc_max_bytes` (32 KiB); later files are cut first	Shorten the core, or move procedures to skills; raise the limit only as a stopgap
Codex ignores your `AGENTS.md` edits in one directory	An `AGENTS.override.md` in the same directory replaces it	Delete the override or merge it; the load-check script shows which one reached the model
Codex loads no project instructions at all	The project is untrusted	Trust the project when Codex asks; confirm with `codex debug prompt-input`
On a Windows clone, `CLAUDE.md` contains only the text `AGENTS.md`	A committed symlink checks out as a text file unless `core.symlinks` is on	Replace the symlink with an `@AGENTS.md` import
The agent follows a rule inconsistently	Two files contradict each other, and the model may pick either	Run the drift audit prompt, or `/doctor prompt-audit` in Claude Code, and keep one source
An agent ran a command the file forbids	Instruction files guide the model; they are not a security boundary	Move the boundary to a deny rule, a hook or CI, and keep the sentence only as an explanation
An access token appears in a rules file	A personal note was committed	Rotate the token first, then remove it from history; keep secrets in environment variables

Where to go next with repository context

Pruning CLAUDE.md and AGENTS.md Cut context files by ablation and keep only the lines that change behaviour.

Claude Code memory in depth Imports, path-scoped rules, auto memory, and how each one loads.

Set up AGENTS.md for Codex Global and project files, and checking what loaded with codex debug prompt-input.

Cursor project rules Cursor's rule types and how to scope them.

One rules source for every agent Generate each tool's files from one source with rulesync or Ruler, and fail CI on drift.

Shared agent rules for a team Ownership, review and rollout of one core across many repositories.

Q6 · Agent skills Move multi-step procedures out of always-loaded context.

Q12 · Agent hooks Enforce the invariants that instruction files can only describe.