Most tutorials about AI agent instruction files tell you what to put in them. Almost none tell you what happens when two of them exist at once — or what the evidence says about whether any of it works.
That gap matters right now, because Claude Code changed how it handles AGENTS.md in the September 18 release, and the change created a trap that's easy to fall into silently. Your instructions can stop being read without any error, warning, or visible difference in behavior. You just get worse results and blame the model.
This article covers the precedence rules as they actually work, a keep/cut framework for what belongs in these files, a 20-minute test to verify your setup, and the honest limitations of all of the above.
The precedence trap
Claude Code reads two kinds of instruction files:
-
CLAUDE.md— Claude Code's native project memory file -
AGENTS.md— a cross-tool convention also read by other coding agents
As of the September 18 change, Claude Code reads AGENTS.md too. The part that trips people up is how it reads them when both exist in the same project.
It's a fallback, not a merge. When both files are present, Claude Code does not concatenate them, does not interleave them, and does not "combine the best of both." One file wins and the other is ignored. CLAUDE.md takes precedence; AGENTS.md is the fallback used when CLAUDE.md is absent.
flowchart TD
A[Claude Code starts a session] --> B{CLAUDE.md present?}
B -- yes --> C[Read CLAUDE.md only]
B -- no --> D{AGENTS.md present?}
D -- yes --> E[Read AGENTS.md only]
D -- no --> F[No project instructions loaded]The failure mode looks like this: you maintain a carefully tuned CLAUDE.md, then add an AGENTS.md so tools like Codex or other agents can share the same instructions. From that moment, every edit you make to AGENTS.md does nothing for Claude Code — and worse, if you move content from CLAUDE.md into AGENTS.md thinking you're consolidating, Claude Code loses those instructions entirely. Nothing errors. The agent just starts forgetting your conventions, and you spend an afternoon wondering why.
The reverse trap: you delete CLAUDE.md during a cleanup, assuming AGENTS.md covers the same ground. It does — but only if the content actually lives there. Fallback means substitution, not union. Anything that existed only in CLAUDE.md is gone.
Practical rule: pick one file per project as the single source of truth. If your team uses multiple agent tools, put the shared content in AGENTS.md and keep CLAUDE.md either absent or containing only Claude-specific additions — never a partial copy, because a partial copy silently shadows the complete file.
What actually belongs in these files
A recent controlled study on agent instruction files (arXiv 2602.11988) tested what kinds of content in files like these measurably change agent behavior. The findings cut against a lot of tutorial advice: long, generic instruction files don't reliably help, and some common categories of content show no measurable benefit or actively hurt by diluting the instructions that do matter.
I want to be careful here: this is one study, and agent behavior varies by model version and task type. But the direction of the evidence is useful, and it matches what practitioners report anecdotally. The pattern that holds up:
| Keep | Cut |
|---|---|
| Build, test, and lint commands (exact commands, not descriptions) | Style guides and code-preference essays |
Project-specific gotchas ("don't touch legacy/", "run migrations before tests") |
Generic best practices ("write clean code", "think step by step") |
| Non-obvious constraints (env vars, ports, required services) | Restating things the agent already knows from the codebase |
File-location pointers ("API types live in src/types/api.ts") |
Long background explainers about the architecture |
The logic is simple: context you spend on content the agent could infer from the code is context not spent on the constraints it couldn't. A one-line "never run npm test without the docker stack up" is worth more than three paragraphs on your commit message philosophy.
There's also a hard size limit to keep in mind — commonly reported around 32 KiB for these context files. Verify the exact current limit against Anthropic's docs before relying on it; I'm flagging it as approximate rather than authoritative because the number has shifted across releases. The practical implication holds regardless of the exact figure: extremely long instruction files risk truncation, and truncation is silent.
The 20-minute A/B protocol
None of the above matters if your specific setup behaves differently. Here's a cheap way to find out, using a task you'd delegate anyway.
- Pick a representative task — something you'd genuinely hand to Claude Code this week: a bug fix, a small feature, a refactor. Not a toy prompt; a real one.
- Run it with your current setup. Note the result: did it follow your conventions? How many correction rounds did you need?
-
Swap the files. If you run both
CLAUDE.mdandAGENTS.md, rename one and re-run the same task. If you only run one file, strip it to the minimum (commands + hard constraints only) and re-run. - Compare. If results are equivalent with the smaller setup, the extra content was costing you context for nothing. If results degrade, you've learned which content actually earns its place — add it back selectively.
Twenty minutes, one task, and you stop guessing. The point isn't statistical rigor; it's converting an invisible configuration question into a visible before/after.
Limitations, honestly stated
- The study cited above is one paper on one set of models and tasks. Treat its conclusions as directional, not definitive.
- The precedence behavior described here reflects Claude Code as of the September 18 change. Agent tooling moves fast; re-verify against current release notes before building a team workflow on it.
- The ~32 KiB figure is approximate and version-dependent — check vendor docs.
- The A/B protocol is anecdotal by design. One task proves nothing statistically; it just beats guessing.
Bottom line
Claude Code reads AGENTS.md as a fallback for CLAUDE.md — not a merge, not a supplement. If both exist, one wins and the other is dead weight that can silently shadow live instructions. Audit which file is actually being read in each of your projects, trim instruction files to commands and constraints the agent can't infer on its own, and verify your setup with a single before/after task rather than trusting a tutorial — including this one.
Sources
- arXiv 2602.11988 — controlled study on agent instruction-file content and effectiveness (primary)
- Anthropic Claude Code release notes and documentation, September 18 update (primary — verify current precedence behavior and file size limits against the live docs)
- AGENTS.md cross-tool specification and adopting-tool documentation (primary)
- Linux Foundation announcement on AGENTS.md standard adoption, including repo adoption figures (secondary)
Researched and drafted with AI assistance, checked against primary sources.
Top comments (0)