AGENTS.md and CLAUDE.md — concise repository context
PLRepository 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.
| 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) | Progressive disclosure: loads only when invoked |
| Hard “never” invariants that must hold | Hooks, permissions and sandboxes, CI | Prose advises; code and sandboxes enforce |
| Active task goals and design trade-offs | intent.md, spec.md, plan.md (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:
# 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:
@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.
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.mdfiles only after you trust the workspace. - Byte budget: Oversized root files silently truncate deeper, more specific nested
AGENTS.mdfiles.
Keep nested conventions in subdirectory AGENTS.md files and consult the OpenAI Codex documentation and Codex AGENTS.md optimization for current discovery and configuration options.
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 and Cursor project rules for current rule syntax and precedence.
Build and wire repository context in five steps
Section titled “Build and wire repository context in five steps”-
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.
-
Strip everything derivable. Delete framework descriptions, folder inventories that
lsreveals, and style rules the linter already enforces. Keep commands, boundaries, and non-obvious invariants. -
Move conditional guidance out of the root. Extract directory-specific rules into nested
AGENTS.mdfiles or path-scoped rules (.claude/rules/,.cursor/rules/*.mdc), and extract multi-step runbooks into Agent Skills. -
Wire thin adapters. Add the
@AGENTS.mdimport inCLAUDE.md, verify workspace trust in Codex, and confirm Cursor picks upAGENTS.mdwithout redundant always-applied rules. -
Assign ownership in
CODEOWNERS. ProtectAGENTS.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:
- Run
@wondelai/harness-audit. Executenpx @wondelai/harness-auditlocally and in CI. Station 1 (Intent) verifies thatAGENTS.mdexists, checks thatCLAUDE.mddelegates via@AGENTS.mdrather than duplicating policy, flags oversized briefs (> 150 lines), and detects scoped rules (harness audit checks reference). - 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).
- 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”| 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, or a PreToolUse hook |
| 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
Section titled “Official docs and next steps”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.
What will you do with it?
How did it read?
What got in the way? Pick any that apply
Your role?
Thanks. I read every answer. Michał Jaskólski
Did this guide help?
One tap each. Close whenever you like.
no sign-in
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.