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

URL: https://developertoolkit.ai/en/workflows/context/agents-md-context/
Description: Write one concise AGENTS.md contract, wire Claude Code, Codex, and Cursor without duplication, and verify which rules every agent loads.

Repository context for coding agents is one concise, versioned `AGENTS.md` contract that defines project layout, exact build and verification commands, explicit boundaries, and the evidence required before work counts as complete. Developers and tech leads use this architecture to wire Claude Code, Codex, and Cursor to a single source of truth so rules never drift across tools.

Last sprint your team changed the unit test command from `npm test` to `pnpm test:unit`. Someone updated `CLAUDE.md` and forgot `AGENTS.md`. Today a Codex session ran the stale command, hit an error, and "fixed" it by rewriting a test script. Duplicated instruction files guarantee silent divergence.

## What belongs in the root AGENTS.md—and what does not

Include a line in the always-loaded root file only when it holds for every task in the repository and an agent cannot infer it from the code or manifests. Target under 150 lines—ideally 40 to 80 lines—so every instruction keeps strong attention across long sessions. Everything else belongs in a layer that loads on demand or enforces deterministically.

| Content | Destination | Rationale |
| --- | --- | --- |
| Layout, exact verification commands, boundaries, completion proof | Root `AGENTS.md` | Needed in every session across all tools |
| Conventions for one directory (`src/billing/`, `infra/`) | Nested `AGENTS.md`, `.claude/rules/*.md`, or `.cursor/rules/*.mdc` | Loads only when working near matching files |
| Multi-step procedures (release, migration, incident response) | [Agent Skill (`SKILL.md`)](/en/ecosystem/skills/) | Progressive disclosure: loads only when invoked |
| Hard "never" invariants that must hold | [Hooks](/en/workflows/harness/agent-hooks/), [permissions and sandboxes](/en/workflows/harness/permissions-and-sandboxing/), CI | Prose advises; code and sandboxes enforce |
| Active task goals and design trade-offs | `intent.md`, `spec.md`, `plan.md` ([artifact chain](/en/method/lifecycle/artifact-chain/)) | Expires when the task ships |
| Personal workflow preferences | User-level config or gitignored local overrides | Never team truth |

A compact root contract fits on one screen:

```md title="AGENTS.md"
# Repository contract
<!-- Owner: @platform-team · review on toolchain or model changes -->

## Layout
- Web app: `apps/web/` · API: `apps/api/` · Shared packages: `packages/`.
- Database migrations live in `apps/api/migrations/`; never edit merged migrations.

## Commands (run from repository root)
- Install: `pnpm install --frozen-lockfile`
- Fast check: `pnpm check:changed`
- Full check: `pnpm typecheck && pnpm lint && pnpm test:unit`

## Boundaries
- Never run commands targeting production or read `.env.production`.
- Stop and propose an ADR before adding a runtime dependency or changing exported APIs.

## Done means
- Full check exits 0; paste exact commands and exit codes in the PR summary.
- List every changed file and flag anything you could not verify locally.
```

Every line names a concrete path, command, or checkable condition. Vague imperatives like "write clean code" or "test thoroughly" waste tokens because neither an agent nor a reviewer can verify compliance.

## How Claude Code, Codex, and Cursor discover one source of truth

Keep all tool-agnostic policy inside `AGENTS.md`, then use the thinnest adapter each tool needs. Avoid committed symlinks when teammates clone on Windows; text imports and native loading are portable.

**Claude Code**

Claude Code reads `CLAUDE.md` hierarchically at startup and loads `.claude/rules/*.md` files scoped by `paths` frontmatter when reading matching files. To guarantee consistent loading across environments without duplicating policy, point `CLAUDE.md` directly at `AGENTS.md` using an `@` import and reserve `CLAUDE.md` strictly for Claude-only directives:

```md title="CLAUDE.md"
@AGENTS.md

## Claude Code notes
- Enter plan mode before modifying `apps/api/migrations/`.
```

Keep directory-specific shared rules in a nested `AGENTS.md` (with a one-line nested `CLAUDE.md` containing `@AGENTS.md` where needed), and use `.claude/rules/<topic>.md` with `paths` globs for Claude-specific path conventions. Note that `@` imports organize files cleanly but still load at startup, so keep imported content short. See the [Claude Code documentation](https://code.claude.com/docs) and [Claude Code memory system](/en/claude-code/build/memory-system/) for current loading mechanics.

**Codex**

Codex reads `AGENTS.md` natively with no adapter. It walks from the project root (typically the nearest `.git`) down to the current working directory, loading `AGENTS.override.md` when present or `AGENTS.md` otherwise, up to its configured byte budget.

Two constraints matter architecturally:
- **Project trust:** Codex loads project-level `AGENTS.md` files only after you trust the workspace.
- **Byte budget:** Oversized root files silently truncate deeper, more specific nested `AGENTS.md` files.

Keep nested conventions in subdirectory `AGENTS.md` files and consult the [OpenAI Codex documentation](https://developers.openai.com/codex) and [Codex AGENTS.md optimization](/en/codex/build/agents-md-optimization/) for current discovery and configuration options.

**Cursor**

Cursor reads `AGENTS.md` directly in the project root and subdirectories alongside `.cursor/rules/*.mdc` project rules. Use `.mdc` files with `description`, `globs`, and `alwaysApply` frontmatter for scoped conventions that attach automatically when touching specific file patterns, and avoid duplicating your root `AGENTS.md` inside always-applied rules.

See the [Cursor documentation](https://cursor.com/docs) and [Cursor project rules](/en/cursor-ide/quick-start/project-rules/) for current rule syntax and precedence.

## Build and wire repository context in five steps

1. **Draft from repository evidence.** Have the agent read your build manifests, CI workflows, and top directory tree, then run every proposed command once and keep only commands that exit 0.

2. **Strip everything derivable.** Delete framework descriptions, folder inventories that `ls` reveals, and style rules the linter already enforces. Keep commands, boundaries, and non-obvious invariants.

3. **Move conditional guidance out of the root.** Extract directory-specific rules into nested `AGENTS.md` files or path-scoped rules (`.claude/rules/`, `.cursor/rules/*.mdc`), and extract multi-step runbooks into [Agent Skills](https://agentskills.io).

4. **Wire thin adapters.** Add the `@AGENTS.md` import in `CLAUDE.md`, verify workspace trust in Codex, and confirm Cursor picks up `AGENTS.md` without redundant always-applied rules.

5. **Assign ownership in `CODEOWNERS`.** Protect `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, and `.cursor/rules/` under required code-owner review. Treat instruction edits like CI pipeline changes.

**Copy-paste prompt: draft a verified root AGENTS.md**

```text
Draft a root AGENTS.md for this repository using only verified evidence:
1. Read the build manifest, CI workflows, README, and top two directory levels.
2. Run each proposed build, typecheck, lint, and test command once; drop any
   command that fails and explain why.
3. Structure strictly into: Layout, Commands, Boundaries, Done means. Keep it
   under 60 lines.
4. Omit anything derivable from source files or already enforced by linters.
Show the draft and each command's exit code before writing any file.
```

## Verify that every agent loaded and applied the rules

Never trust that a committed instruction file reaches the model. Combine automated static checks with a live probe:

1. **Run `@wondelai/harness-audit`.** Execute `npx @wondelai/harness-audit` locally and in CI. Station 1 (Intent) verifies that `AGENTS.md` exists, checks that `CLAUDE.md` delegates via `@AGENTS.md` rather than duplicating policy, flags oversized briefs (> 150 lines), and detects scoped rules ([harness audit checks reference](/en/reference/harness-audit-checks/)).
2. **Inspect loaded context in each tool.** Confirm loaded memory files in Claude Code's context inspector and verify rendered prompt inputs in Codex's debug inspection tools (see official vendor docs for exact commands).
3. **Run a behaviour probe on rule changes.** Paste the probe below into a fresh session after editing instructions and attach the output to the pull request.

**Copy-paste prompt: fresh-session discovery and behaviour probe**

```text
Without searching the repository, answer from your loaded instructions only:
1. List the exact paths of the repository instruction files loaded for this session.
2. Quote the exact commands required for unit tests, typecheck, and lint.
3. List every forbidden action and boundary stated in your instructions.
4. Open one file in `src/billing/` (read-only) and state which scoped conventions
   apply to it and how you would represent 19.99 EUR in code.
If any item is missing from your loaded instructions, state "none loaded".
```

Apply the **two-strike rule** for maintenance: add a new line only after the same mistake occurs twice in separate sessions and can be stated as a checkable condition. When the file grows past your budget, run the [ablation protocol](/en/workflows/context/pruning-context-files/).

## When AGENTS.md and CLAUDE.md silently fail

| Symptom | Root cause | Recovery |
| --- | --- | --- |
| Claude Code skips `AGENTS.md` after someone adds a local note | A local `CLAUDE.md` or `CLAUDE.local.md` overrides fallback discovery | Keep `CLAUDE.md` importing `@AGENTS.md` explicitly in the repository |
| Codex follows root rules yet ignores nested conventions | Combined `AGENTS.md` files exceeded the byte budget, truncating deeper files first | Shorten the root file and move procedures into `SKILL.md` skills |
| Codex ignores all project instructions | The workspace has not been marked trusted | Trust the project in Codex and re-run the discovery probe |
| Agents follow a rule inconsistently across sessions | Two files contradict each other (`AGENTS.md` vs `.cursor/rules/` or `CLAUDE.md`) | Audit all instruction files for duplicates and keep policy exclusively in `AGENTS.md` |
| An agent executes a command explicitly forbidden in prose | Context files guide attention; they are never a security boundary | Move the prohibition into [permissions, sandboxes](/en/workflows/harness/permissions-and-sandboxing/), or a [`PreToolUse` hook](/en/workflows/harness/agent-hooks/) |
| A credential appears in a committed instruction file | Personal notes were staged into shared rules | Rotate the credential immediately, purge history, and enforce secret scanning |

## Official docs and next steps

Check vendor documentation for current discovery rules, frontmatter fields, and memory inspection commands: [Claude Code docs](https://code.claude.com/docs), [OpenAI Codex docs](https://developers.openai.com/codex), [Cursor docs](https://cursor.com/docs), and [Agent Skills](https://agentskills.io).

- [Pruning context files](/en/workflows/context/pruning-context-files/) — Cut bloated instruction files by ablation and restore only lines proven by failures.
- [Context windows and token limits](/en/workflows/context/context-windows/) — Keep constraints alive across compaction and long multi-phase tasks.
- [Team collaboration and shared rules](/en/teams/adopt/team-collaboration/) — Govern ownership, review, and rollout of one contract across repositories.
- [Agent hooks](/en/workflows/harness/agent-hooks/) — Move non-negotiable invariants out of prose into deterministic scripts.
