On this page#
- How we judged them
- The shortlist
- Scope
- Architecture
- Verification
- Navigation
- What we rejected and why
- The one nobody talks about
- Choosing by repo shape
- FAQ
How we judged them#
A useful AGENTS.md makes agent behavior more predictable without pretending a prompt can replace repository structure, tests, or review. For a real codebase, the winning configuration is the smallest one that communicates durable invariants, routes the agent to local context, and remains correct as the repository changes.
An large language model predicts outputs from context; it does not independently know which conventions in your repository are intentional. Instructions help, but only when they are specific enough to constrain decisions and stable enough to trust.
We judge an AGENTS.md setup on six criteria:
- Correct loading: Does the active tool actually read it?
- Scope: Can instructions differ between the repository root and specialized subtrees?
- Durability: Will the guidance still be true after the next refactor?
- Verifiability: Does it point to commands and checks that can prove a change is acceptable?
- Conflict handling: Is precedence obvious when local and global guidance disagree?
- Maintenance cost: Will engineers update it, or will it become ceremonial documentation?
The first criterion is non-negotiable. Claude Code’s documented project-memory mechanism is CLAUDE.md, not a generic promise that every agent instruction filename will be discovered automatically. Check the current behavior in the Claude Code official documentation, and make the loading path explicit.
A good file contains repository-specific constraints such as:
- Where architectural boundaries sit.
- Which generated files must not be edited.
- Which commands verify a change.
- Which directories own their own instructions.
- Which compatibility promises must survive.
- Where the canonical documentation lives.
A bad file contains generic advice such as “write clean code,” “consider edge cases,” or “follow best practices.” Those sentences consume context while settling no real decision.
Photo by mali maeder on Pexels.
The shortlist#
There is no universally best claude code agents.md layout. Choose the layout that matches the repository’s ownership boundaries and failure modes. For most established codebases, a thin shared AGENTS.md plus an explicit Claude Code adapter is the strongest default; deeper layering is justified only when subtrees genuinely behave differently.
| Configuration | Best for | When not to use it |
|---|---|---|
| Thin root AGENTS.md with a root CLAUDE.md adapter | A repository using Claude Code alongside Codex, Cursor, or other agents | When every tool already follows one native instruction format and cross-tool consistency has no value |
| Root file plus subtree instruction files | Monorepos, polyglot systems, or products with distinct deployment and testing boundaries | When the repository is small or the local files would repeat the root |
| Native CLAUDE.md only | Teams standardized entirely on Claude Code | When contributors use multiple agents and duplicated policies will drift |
| Generated instruction files | Repositories with an existing machine-readable source of truth | When generation hides ownership or engineers cannot easily review the resulting instructions |
| No persistent agent file | Small, rapidly changing, or highly experimental repositories | When important invariants are undocumented and mistakes are expensive |
For the default setup, keep AGENTS.md tool-neutral and make CLAUDE.md the explicit Claude-facing entry point. The adapter should contain little beyond the connection to shared guidance and any genuinely Claude-specific instructions. The official Claude Code overview should remain the authority for what Claude Code loads and how its project context works.
The shared file should read more like an operating contract than a style guide:
# Repository instructions
## Scope
These rules apply repository-wide unless a narrower instruction file overrides them.
*Photo by Christina Morillo on [Pexels](https://www.pexels.com/photo/man-wearing-blue-dress-shirt-facing-whiteboard-1181343/).*
## Architecture
- Keep domain code independent of transport and persistence layers.
- Do not edit generated artifacts directly.
- Preserve public interfaces unless the task explicitly authorizes a breaking change.
## Verification
- Run the narrowest relevant checks first.
- Run the repository’s required validation before declaring completion.
- Report checks that could not be run.
*Photo by Lukas Blazek on [Pexels](https://www.pexels.com/photo/person-encoding-in-laptop-574071/).*
## Navigation
- See the canonical architecture document for subsystem boundaries.
- Follow subtree instructions where present.Do not paste the architecture document into this file. Route to it. If you need practical agent setups rather than another abstract checklist, the PairFoundry tools page is the natural next stop.
What we rejected and why#
We rejected configurations that look comprehensive but make the agent less trustworthy. The recurring failure is treating instructions as a second repository: policies, commands, architecture, and exceptions get copied into one large file, then quietly diverge from the code and canonical documentation.
The giant repository manual#
A thousand-line instruction file is not “more context.” It is an unprioritized context dump. Critical constraints compete with directory tours, formatting preferences, and historical explanations.
Keep only information that changes how the agent should act. Link to canonical material for everything else. Claude Code’s own behavior should be taken from the official documentation, not restated from memory inside the repository.
Identical files for every tool#
Copying the same policy into AGENTS.md, CLAUDE.md, editor rules, and CI documentation creates multiple sources of truth. The files will drift because nothing forces simultaneous updates.
Use one shared policy plus thin adapters. Tool-specific files should contain only loading glue and behavior that truly belongs to that tool.
Instructions that replace enforcement#
“Do not cross this dependency boundary” is useful context, but it is not enforcement. If violating the boundary matters, encode it in tests, linters, build rules, or module visibility.
The instruction explains intent; automation catches violations. Confusing those roles is a serious engineering mistake.
A generated file with no obvious provenance#
Generation is acceptable only when the source, generator, and update path are visible. A generated AGENTS.md that engineers hand-edit—or cannot trace—is worse than a short maintained file.
For broader comparisons of agent practices and their tradeoffs, use The Landscape as the category hub rather than expanding repository instructions into an industry essay.
The one nobody talks about#
The underrated option is a deliberately boring adapter: keep shared repository rules in AGENTS.md, then use a tiny CLAUDE.md to make those rules visible to Claude Code. This preserves cross-tool consistency while respecting Claude Code’s documented instruction mechanism instead of assuming filename interoperability.
The adapter has three jobs:
- Load or point Claude Code to the shared instructions using the supported project-memory mechanism.
- State which file wins if shared and Claude-specific guidance conflict.
- Hold the few instructions that apply only to Claude Code.
That is all. It should not become a shadow copy.
This pattern also creates a clean rollback. If the shared policy causes bad behavior, remove or narrow the adapter reference, inspect the conflicting instruction, and restore it only after the rule is made precise. You are changing context, not rewriting repository history.
Teams not ready to formalize this contract should start with the PairFoundry foundations track. The important prerequisite is not prompt sophistication; it is knowing which repository facts are durable enough to encode.
Choosing by repo shape#
Match instruction topology to repository topology. A single service usually needs one short shared contract. A monorepo needs scoped guidance at real boundaries. A regulated or compatibility-sensitive system needs stronger verification instructions. A chaotic repository may need no persistent file until its conventions become stable.
| Repository shape | Recommended setup |
|---|---|
| Single service, one stack | Thin root AGENTS.md plus a Claude adapter |
| Monorepo with independent packages | Root invariants plus local files at package boundaries |
| Polyglot repository | Root ownership rules plus language-specific verification guidance |
| Legacy system with fragile compatibility | Short global file emphasizing protected interfaces, characterization tests, and escalation points |
| Generated-code-heavy repository | Explicit generated paths and source-generation commands |
| Rapid prototype | No file, or a minimal temporary contract reviewed frequently |
| Claude Code-only team | Native CLAUDE.md, unless future cross-tool portability is a stated goal |
Layer by behavior, not directory count. A subtree deserves local instructions when it has different commands, ownership, architectural rules, or release constraints—not merely because it exists.
For a monorepo, the root should define universal invariants and precedence. Local files should describe only the delta. Repeating root rules in every package increases maintenance without improving agent decisions.
For a legacy codebase, prioritize what must not change. “Modernize this area” is vague; “preserve this public interface and run these compatibility checks” is operational. The PairFoundry packs provide the consolidated view when you want a packaged workflow rather than assembling every convention independently.
Whatever the shape, treat instruction changes like code changes: review the diff, identify affected scopes, and verify that the file still points to canonical commands. If engineers cannot tell which rule governed an agent decision, the configuration is too complicated.
Related reading#
- Best AI for vibe coding for people who already have a real codebase
- Best Claude Code skills — ranked by how little you have to babysit them
FAQ#
Should our team use AGENTS.md or CLAUDE.md?#
Use CLAUDE.md as the documented Claude Code entry point. Use AGENTS.md as the shared, tool-neutral contract when multiple coding agents need the same repository rules. Connect them explicitly; do not assume Claude Code automatically treats every convention as native.
How do we stop root and package-level instructions from contradicting each other?#
Define precedence in the root file and make local files contain only exceptions or additions. If the same rule appears in multiple places, consolidate it. A conflict that requires the agent to infer authorial intent is a configuration bug.
What should we do when an instruction makes Claude Code perform worse?#
Remove or narrow the offending rule first. Then identify whether it was vague, stale, over-broad, or competing with another instruction. Restore it only after rewriting it as a scoped, verifiable constraint. Do not compensate by adding several more prompts.
When should we avoid persistent agent instructions entirely?#
Avoid them when repository conventions are changing faster than the file can be maintained, when no one owns updates, or when the content would be generic advice. Stale authority is more dangerous than missing context because the agent has reason to trust it.
Can AGENTS.md enforce architectural rules?#
No. It can explain boundaries and direct the agent toward the right implementation, but enforcement belongs in tests, dependency checks, linters, build configuration, and review. Use the file to communicate intent; use automation to reject violations.