Skip to content

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

Section titled “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.

ContentDestinationRationale
Layout, exact verification commands, boundaries, completion proofRoot AGENTS.mdNeeded in every session across all tools
Conventions for one directory (src/billing/, infra/)Nested AGENTS.md, .claude/rules/*.md, or .cursor/rules/*.mdcLoads only when working near matching files
Multi-step procedures (release, migration, incident response)Agent Skill (SKILL.md)Progressive disclosure: loads only when invoked
Hard “never” invariants that must holdHooks, permissions and sandboxes, CIProse advises; code and sandboxes enforce
Active task goals and design trade-offsintent.md, spec.md, plan.md (artifact chain)Expires when the task ships
Personal workflow preferencesUser-level config or gitignored local overridesNever team truth

A compact root contract fits on one screen:

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

Section titled “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 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:

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 and Claude Code memory system for current loading mechanics.

Build and wire repository context in five steps

Section titled “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.

  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.

Verify that every agent loaded and applied the rules

Section titled “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).
  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.

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.

When AGENTS.md and CLAUDE.md silently fail

Section titled “When AGENTS.md and CLAUDE.md silently fail”
SymptomRoot causeRecovery
Claude Code skips AGENTS.md after someone adds a local noteA local CLAUDE.md or CLAUDE.local.md overrides fallback discoveryKeep CLAUDE.md importing @AGENTS.md explicitly in the repository
Codex follows root rules yet ignores nested conventionsCombined AGENTS.md files exceeded the byte budget, truncating deeper files firstShorten the root file and move procedures into SKILL.md skills
Codex ignores all project instructionsThe workspace has not been marked trustedTrust the project in Codex and re-run the discovery probe
Agents follow a rule inconsistently across sessionsTwo 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 proseContext files guide attention; they are never a security boundaryMove the prohibition into permissions, sandboxes, or a PreToolUse hook
A credential appears in a committed instruction filePersonal notes were staged into shared rulesRotate the credential immediately, purge history, and enforce secret scanning

Check vendor documentation for current discovery rules, frontmatter fields, and memory inspection commands: Claude Code docs, OpenAI Codex docs, Cursor docs, and Agent Skills.

Did this guide help you?

One tap, no sign-in.

not at all a lot

Frequently asked questions

What belongs in a repository `AGENTS.md` or `CLAUDE.md` file?

A concise repository context file states the project layout, exact build and test commands, explicit boundaries, and the verification proof required before work counts as complete.

How do you verify which instruction files Claude Code, Codex, and Cursor actually loaded?

Run deterministic checks with @wondelai/harness-audit, inspect loaded memory files using each tool's built-in context inspector, and run a fresh-session behaviour probe that quotes active rules and commands.