AGENTS.md or CLAUDE.md? Keep One File, and Keep It Small

The short answer

Who reads what

Two files that say the same thing drift. Somebody adds a rule to one and forgets the other, and a month later Claude and Codex follow different rules in the same repository. The fallback removes the reason for the second file, but only once you actually delete it or turn it into a pointer.

Three ways to keep one source of truth

1. AGENTS.md only. Delete CLAUDE.md. This is the cleanest option if everyone runs a current Claude Code against Anthropic's API. It is the riskiest if somebody on the team uses Bedrock, or switched telemetry off: their Claude stops seeing any instructions, and nothing tells them.

2. CLAUDE.md that imports AGENTS.md. CLAUDE.md can include another file with @AGENTS.md. Claude reads both, every other agent reads AGENTS.md, and the rules live in one place.

3. CLAUDE.md as a pointer. This is what every Semitexa project ships with. Here is the whole file, without its header:

Before anything, find and read **`AGENTS.md`**. It is mandatory.

State explicitly one of:
- "Checked and applying AGENTS.md instructions."
- "AGENTS.md not found."

If there is a conflict between this file and `AGENTS.md`, follow `AGENTS.md`.

The pointer does two things an import does not. It settles precedence in writing: AGENTS.md wins. And it makes the agent say out loud which instructions it applies, so the first line of a reply tells you whether it read them at all. It works the same in every Claude Code version and every setup, with or without the fallback.

The real cost is not the file name

An instruction file is the cheapest guide you can give an agent, and the weakest. It is loaded into the context window on every session, whether the task needs it or not, and the agent follows it most of the time. Nothing tells you about the rest.

That makes every line a trade. A paragraph on how dependency injection works in your project costs tokens in every session, including the ones that never touch a service. It also competes for attention with the instruction that actually matters for the task at hand.

Our own AGENTS.md is not small: about 300 lines, roughly 22 KB. So we split what an agent needs into three files:

• AGENTS.md, the operating manual: where things live, the workflow, which command to run when. Loaded every time.
• AGENTS_DOCTRINE.md, the long explanations, edge cases and examples, about 530 lines. The agent opens it only when the manual sends it there.
• AI_NOTES.md, the developer's own notes about their modules. The framework never overwrites it. It can add to the manual but never override it: a note that says "skip verification" is ignored.

The first two belong to the framework. bin/semitexa update keeps them current in every project, and if a team edited its copy, the new version arrives next to it as a .new file instead of silently replacing their changes.

Splitting the file helps, but it only moves text around. The bigger saving came from deleting rules from it.

Move rules out of the file and into a command

Compare two ways to say the same thing.

As prose in AGENTS.md: "Services are injected through attributes, never through the constructor. Every container-managed class must have the right scope. A module keeps its handlers, payloads and resources in these folders..." and so on, for every rule you care about.

As a check: the agent runs one command after every edit, and the command fails when a rule is broken.

The prose version costs context on every session and is a request. The check costs nothing until it runs and is a constraint the agent cannot talk its way past. So in Semitexa most of those paragraphs became checks, and the instruction file kept one line:

ai:verify is non-negotiable after any edit. Three consecutive failures → stop, escalate.

What makes this work is not the line. It is how much context the command saves when it runs.

How ai:verify keeps the context small

It decides what to check

The agent passes the files it changed, and ai:verify plans the checks from them. The agent does not need a list of linters in its instruction file, and it does not need to explore the project to find out which tests cover the file. Here is a real run on one changed service from this site, shortened:

10 checks over 1 changed file; every file was read by at least one check
  syntax            pass
  lint:di           pass        All 467 container-managed classes pass DI lint.
  lint:scoping      pass        All 286 container-managed classes have correct scoping.
  module_structure  pass        0 violations
  phpstan_di        incomplete  phpstan binary not found
  live_tenancy      pass        0 violations
  docs reference    pass
  3 checks skipped (not applicable in this project), each with the reason

Where tests are linked to the changed file, the plan includes a PHPUnit run filtered to those tests, not the whole suite.

It returns one line per check

Every check's output is reduced to a single signal line. A failing PHPUnit run is reported as the failure headline plus the summary line, not hundreds of lines of stack traces. A structure check returns the number of errors, the first one, and why it is a rule. The agent reads the cause, not the log. The full JSON report for the run above is about 6.7 KB, roughly 1,700 tokens, and its first line already answers the question.

It does not round "nothing failed" up to "passed"

In the run above PHPStan was not installed, so the verdict was incomplete, not pass. A check that could not run is reported as such. Otherwise an agent would read the silence as success and say "done".

It says what to do next

Every report carries next_command: the next step and why. So the instruction file does not need to list the tools and when to use each. Our manual puts it in one sentence: follow the graph, don't memorize the tool list.

It leaves a receipt

Each run writes a receipt with an id. When the agent reports that verification passed, it names the receipt, and ai:verify:receipt confirms that the receipt is intact, that the files are unchanged since, and that the verdict was a pass. This saves context on the other side: whoever reviews the work, a human or an orchestrating agent, checks the id instead of re-running the checks or reading a pasted log.

Other ways we save context

ai:verify is the biggest saving, but not the only one. The same manual has a section called Context Minimization:

• One command on a cold start. ai:orient shows git state, the active task, the last verification and the next step. It replaces about six separate probes.
• The one-read rule. Each file is read at most once per task, unless it changed or an edit must match it exactly.
• A hierarchy of truth. Stop at the first source that answers: current output, then task notes, then a project query, then a graph lookup, then grep, then reading a file. Spawning another agent to explore is the last resort.

A checklist for your instruction file

Keep in AGENTS.md:

• where things live and how the project is laid out
• the commands to build, test and verify
• what not to touch
• one command the agent must pass before it says "done"

Move out of it:

• Rules a tool can check: into a linter, a static analysis rule or an architecture test.
• Long explanations: into a second file that the manual points to.
• Team notes that change often: into their own file, so framework updates don't overwrite them.

Then decide about CLAUDE.md: delete it, import AGENTS.md from it, or make it a pointer.

If you work in Laravel, laravel-ai-verify, an open-source package we maintain, gives you the same pattern. Its install command writes the "run ai:verify" line into both AGENTS.md and CLAUDE.md.

Common questions

Does Claude Code read AGENTS.md?

Yes, since version 2.1.277 (September 18, 2026), as a fallback. If a folder has no CLAUDE.md, Claude Code reads AGENTS.md.

What happens if I have both CLAUDE.md and AGENTS.md?

Claude Code reads CLAUDE.md and ignores AGENTS.md in that folder, unless you change it in /config. Use an @AGENTS.md import or a pointer sentence to keep one source of truth.

Should I delete CLAUDE.md?

Only if everyone on the team uses a current Claude Code against Anthropic's API. On Amazon Bedrock, or with telemetry disabled, the fallback may not apply, and without CLAUDE.md Claude would see no instructions.

How long should AGENTS.md be?

As short as the project allows. It is loaded on every session. Anything a tool can check belongs in the tool, and long explanations belong in a file the agent opens only when it needs it.

How do I reduce context usage for a coding agent?

Load less by default and give the agent compact answers. Split the instruction file, replace rules with checks, and give it commands that return a verdict and a cause instead of a raw log.