# AGENTS.md and CLAUDE.md — concise repository context

URL: https://developertoolkit.ai/en/developer-scorecard-guide/claude-md-context/
Description: Write one short AGENTS.md core, wire Claude Code, Codex and Cursor to it, and prove with /context and codex debug prompt-input which rules each agent loaded.

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](/en/developer-scorecard-guide/). Team-wide governance of the same files is the job of [shared agent rules](/en/cto-scorecard-guide/shared-agent-rules/).

**Scorecard Q9: what the top answer looks like**

**Question (paraphrased):** How is institutional codebase knowledge configured (`CLAUDE.md`, `.cursor/rules/`, `AGENTS.md`)?

**Top answer:** a tiered hierarchy (a root instruction file plus path-scoped rules) that grows only when a mistake repeats. The evidence that earns it: the files are versioned and owned, every command in them runs, and a fresh session in each tool reports the expected rule set.

## 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](/en/developer-scorecard-guide/agent-skills/) | Loads on demand |
| "Never" rules that must hold | [Hooks](/en/developer-scorecard-guide/agent-hooks/), [permissions and sandboxing](/en/workflows/harness/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](/en/method/lifecycle/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:

```md title="AGENTS.md"
# 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](https://code.claude.com/docs/en/memory), 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**

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. Both release channels have it (`stable` is v2.1.292 on 2026-10-17), so only a teammate on an older build does not get the direct read.

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

```md title="CLAUDE.md"
@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).

```md title=".claude/rules/billing.md"
---
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:

```md title="apps/api/src/billing/CLAUDE.md"
@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](https://code.claude.com/docs/en/memory) 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**

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

Cursor applies instructions through **Rules** ([cursor.com/docs/rules](https://cursor.com/docs/rules), checked 2026-10-12). Project rules live in `.cursor/rules/` as `.mdc` files (a plain `.md` file there is ignored), the directory Claude Code's `/init` also reads when it drafts `CLAUDE.md`. Cursor also supports `AGENTS.md` in the project root and in subdirectories, where more specific files take precedence, and reads `CLAUDE.md` files the same way; `CLAUDE.md` files are always applied (Cursor docs, checked 2026-10-12).

- **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](/en/ecosystem/frameworks/rules-sync/).

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

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

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

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

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

5. **Wire the adapters** from the tabs above: `CLAUDE.md` with `@AGENTS.md`, nothing for Codex, a probe and possibly a pointer rule for Cursor.

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

**Copy-paste prompt: draft the core from repository evidence**

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

**Claude Code**

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

```json title=".claude/settings.local.json"
{
  "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**

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

```bash title="scripts/check-agent-context.sh"
#!/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.

**Cursor**

Cursor's load check is the discovery probe below, run in a new Agent chat. Record the answer in the pull request that changes the rules, so the reviewer can compare it with the expected rule set.

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

**Copy-paste prompt: discovery probe**

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

**Copy-paste prompt: scoped-rule probe**

```text
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](/en/workflows/context/pruning-context-files/) removes lines one at a time and restores only what breaks.

**Copy-paste prompt: drift and contradiction audit**

```text
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 (both release channels are past it on 2026-10-12), 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](/en/workflows/context/pruning-context-files/) — Cut context files by ablation and keep only the lines that change behaviour.
- [Claude Code memory in depth](/en/claude-code/build/memory-system/) — Imports, path-scoped rules, auto memory, and how each one loads.
- [Set up AGENTS.md for Codex](/en/codex/quick-start/agents-md/) — Global and project files, and checking what loaded with codex debug prompt-input.
- [Cursor project rules](/en/cursor-ide/quick-start/project-rules/) — Cursor's rule types and how to scope them.
- [One rules source for every agent](/en/ecosystem/frameworks/rules-sync/) — Generate each tool's files from one source with rulesync or Ruler, and fail CI on drift.
- [Shared agent rules for a team](/en/cto-scorecard-guide/shared-agent-rules/) — Ownership, review and rollout of one core across many repositories.
- [Q6 · Agent skills](/en/developer-scorecard-guide/agent-skills/) — Move multi-step procedures out of always-loaded context.
- [Q12 · Agent hooks](/en/developer-scorecard-guide/agent-hooks/) — Enforce the invariants that instruction files can only describe.
