Design AGENTS.md as a small shared contract: put repository-wide constraints in the root file, package-specific rules in nested files, and give every rule one owning document. The format has no required fields because agents parse standard Markdown, so scope, precedence, and completion checks must be explicit. To carry the same contract across coding agents, verify discovery from the working directory rather than assuming Codex, Claude Code, and Cursor load the same filenames or combine instructions in the same way (AGENTS.md, Codex, Claude Code, and Cursor).
Set up AGENTS.md
Start with a root file that applies to the whole repository. Keep information there only when it remains true across packages: repository purpose, architectural boundaries, shared commands, generated-file restrictions, and the definition of a verified result.
For a monorepo, add files where the context changes:
repository/
├── AGENTS.md
└── packages/
├── web/
│ └── AGENTS.md
└── api/
└── AGENTS.md
The AGENTS.md project guidance recommends a nested file for each package. Its precedence model gives the closest applicable instruction priority, which makes a nested file suitable for package-specific commands and constraints. Do not repeat a repository rule in every package unless the package genuinely overrides it; duplication creates two places to update and makes conflicts harder to understand.
A practical file can use ordinary Markdown headings:
This file applies to [repository or package].
# Before editing
- Read [required project documents].
- Preserve [shared, generated, or active files].
- Confirm [task prerequisite].
# Execution
- Use [actual setup command] when required.
- Run [actual task-relevant check].
# Done means
- Read the result from [user-visible or persisted location].
- Report [failure, blocked state, or exact next step].
# Coordination
- Edit only [assigned scope].
- Follow [named ownership or handoff rule].
These headings are a design choice, not reserved fields. Replace every bracketed item with an actual path, command, boundary, or observable result. “Be careful” is not a completion check. “Read the generated page and confirm that the new section contains the expected text” tells the agent what evidence closes the task.
Keep the entry file short enough to scan and route readers to deeper documents when detail is conditional. In our setup, one startup file is the single entry point: it says what to do, how success is recognized, and where detailed guidance lives. Each rule has exactly one owning document; other files link to that owner instead of copying it.
Then check portability before treating the file as shared infrastructure. This comparison comes from each product’s documentation; we have not run or benchmarked these tools.
| Coding agent | Document behavior | Design consequence |
|---|---|---|
| Codex | At global scope, its home directory—~/.codex unless CODEX_HOME is set—checks AGENTS.override.md, then AGENTS.md, using the first non-empty file. At project scope, Codex walks from the project root to the current directory, checks the same names plus configured fallbacks, includes at most one file per directory, and merges files from root down. |
Put the portable baseline in AGENTS.md; reserve Codex-specific overrides for instructions that should replace it. |
| Claude Code | Direct reading of AGENTS.md requires Claude Code v2.1.277 or later. By default, it reads the file only when no CLAUDE.md exists in the working directory or above it. Claude Code does not read AGENTS.local.md, AGENTS.override.md, or files under .agents/. |
Check for competing CLAUDE.md files and avoid assuming that every AGENTS filename works in Claude Code. |
| Cursor | A root AGENTS.md is an alternative to .cursor/rules for straightforward use cases. Nested AGENTS.md files are combined with parent files, and more specific instructions take precedence. |
Keep the shared file at the root and use nested files for package deltas rather than replacing the root contract. |
When Claude Code is not reading AGENTS.md directly, its documented fallback is an import in a CLAUDE.md next to the shared file:
# CLAUDE.md
@AGENTS.md
This keeps the substantive instructions in AGENTS.md instead of maintaining a second copy. The Claude Code memory documentation provides that import behavior.
Codex also exposes two settings that matter when designing the layout. project_doc_fallback_filenames lets an existing filename such as TEAM_GUIDE.md act as an instructions file, while project_doc_max_bytes limits the combined project documentation; its documented default is 32 KiB. Empty files are skipped, and Codex stops adding files when the combined size reaches the limit. Check the current Codex documentation for configuration syntax rather than guessing at the placement or value type.
Check it worked
Run filesystem checks from the directory where the agent will work, especially inside a package:
pwd
git rev-parse --show-toplevel
find "$(git rev-parse --show-toplevel)" -name AGENTS.md -print
find "$(git rev-parse --show-toplevel)" -name CLAUDE.md -print
cat AGENTS.md
The important result is not merely that a file exists. Confirm that the root file and every applicable nested file are visible from the current path. Codex normally walks from the project root, typically the Git root, to the current directory; if it cannot find a project root, its documented fallback is to check only the current directory. See the Codex AGENTS.md guide for the full discovery order.
Next, run a no-write probe. Ask the agent to identify the scope governing the file it would change, the shared rule that applies, and the exact check that would prove completion. Then perform one representative task and inspect the result where a user would encounter it. An agent summary, successful build, or successful command is a signal, not the final check.
In our setup, done means the result has been read back from its persisted or user-visible location. For visual output, inspect the content rather than accepting the existence of a screenshot or image file. A new verification gate must also be exercised with a case that should fail; otherwise, a copied gate can report success without testing anything relevant.
Where it breaks
Precedence collisions
The first failure mode is assuming that “nearest file wins” means every tool uses the same loading algorithm. The AGENTS.md FAQ says the closest file to the edited file wins and that explicit user chat prompts override the file guidance. Codex instead describes a root-to-current-directory merge in which later, closer files override earlier guidance, while Cursor describes nested files as combined with parent instructions.
Do not encode the same topic in both a root file and a nested file unless the relationship is intentional. State the package scope clearly, remove obsolete duplicates, and test from the directory where the agent will actually edit.
Competing filenames and versions
A repository may be correct for one agent and incomplete for another. A CLAUDE.md above the working directory changes Claude Code’s default direct-reading behavior, and names recognized elsewhere do not become portable automatically. In particular, the Claude Code documentation explicitly excludes AGENTS.local.md, AGENTS.override.md, and .agents/ content from direct reading.
Keep AGENTS.md as the canonical shared file. Use a neighboring import when Claude Code needs the documented bridge, and check the required Claude Code version before rollout. Cursor’s rules documentation describes AGENTS.md and nested AGENTS.md files but does not say that the Codex override filename is loaded; do not infer that portability.
Size limits and vague rules
Codex’s combined project-document limit can create a failure that a local file inspection will not reveal. The other products’ documentation does not say they enforce the same combined limit, so treat 32 KiB as a Codex-specific design constraint rather than a universal AGENTS.md budget. Put package detail in nested files, but remember that a deeply nested instruction still depends on discovery from the working path.
Because AGENTS.md is ordinary Markdown without required fields, there is no field-level validation signal to rescue ambiguous wording. Replace vague directives with paths, ownership boundaries, commands that already exist in the project, and observable completion conditions.
Shared working directories
Loader correctness does not prevent concurrency damage. In our shared working directories, uncommitted changes belong to every active session, not only the one that notices them. Our operating rules therefore require one writer per file, a re-read before editing, atomic replacement through a temporary file, session-specific scratch directories, and commits limited to the agent’s own lines.
Put those boundaries in the shared operating document when agents work side by side. They are operating controls, not filename features, but they determine whether the instructions produce safe work after they have been loaded.
A portable AGENTS.md system is therefore not one giant prompt. It is a concise root contract, scoped package deltas, one owner for each rule, and checks that account for each loader’s actual behavior.