What Should Go in AGENTS.md and CLAUDE.md?

A repository instruction file can easily become a compressed README, an architecture essay, and a list of admirable engineering principles. The agent then receives that material on every task—even when most of it is irrelevant.

Recent benchmark results suggest a narrower job for these files. Use AGENTS.md and CLAUDE.md as short operating manuals: exact commands, expensive operations, verification steps, boundaries, and facts that are hard to infer from the code. Do not expect a longer project description to supply engineering judgment the model does not already have.

Quick answer #

Put a fact in the root instruction file when all three are true:

1. It applies to most work in that scope.
2. The agent cannot discover it quickly and reliably from the repository.
3. Following it changes an observable action or check.

Good examples are:

• pnpm test --filter api is the fast test command for API changes.
• The full integration suite takes 25 minutes and should run once, after targeted tests pass.
• Files under generated/ must be changed through pnpm generate.
• Adding a production dependency or changing a database migration requires confirmation.
• A change is incomplete until the type check and the relevant focused test pass.

Leave out broad statements such as “write clean code,” copied package lists, and descriptions the agent can obtain by reading the manifest and source tree. Use a task prompt for one-off requirements, a skill for an on-demand procedure, and tests, hooks, or CI for rules that must be enforced mechanically.

AGENTS.md and CLAUDE.md are similar, but not identical #

Both files provide persistent repository instructions, but their discovery and scope rules belong to the agent that reads them.

Codex builds its instruction chain once per run or launched TUI session. It checks global guidance, then walks from the project root to the current working directory. A closer file appears later in the combined prompt and therefore overrides broader guidance. The exact discovery order and override behavior are in the Codex AGENTS.md documentation.

Claude Code treats CLAUDE.md as context rather than enforced configuration. Its documentation recommends specific, concise instructions and explains that large or conflicting files reduce adherence. See How Claude remembers your project.

If a team uses both agents, keep shared instructions in AGENTS.md and import them from a small CLAUDE.md:

@AGENTS.md

## Claude Code only

- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.

Anthropic documents this import pattern directly. A symlink can also work, but the import leaves room for a small amount of Claude-specific guidance and is more portable on Windows.

What the latest two-agent study tested #

The July 2026 preprint Do Context Files Help Coding Agents? turned merged pull requests from three Python repositories—PDM, firebase-admin-python, and opshin—into 17 coding tasks. The PR description was the prompt, while tests introduced by the real PR remained hidden and judged the agent’s implementation.

Claude Code and Codex each worked under three conditions:

• none: no repository context file;
• always on: the complete AGENTS.md was inserted into every turn;
• selective: the agent received a hint and could read topic-organized wiki files when needed.

After three repeats, 288 runs had valid correctness results:

The differences were not statistically significant. In the authors’ manual review, near misses failed because of feature design, pattern selection, or incorrect wiring—not a missing repository fact that the real AGENTS.md contained. Adding or reorganizing that context did not turn those failures into passes.

That result does not prove instruction files never improve correctness. The sample contains only three Python repositories and 15–17 tasks per agent. The paper’s power analysis estimates that detecting a 10-percentage-point effect would require roughly 120–200 tasks. It also tested stronger, artificial injection rather than simply leaving a file in its natural workspace location: Claude received an appended system prompt, while Codex received text prepended to the user prompt.

The selective condition has another limitation. Its wiki matched the original AGENTS.md only for opshin; the other two repositories received broader generated wikis about 10 and 18 times longer. Selective retrieval is therefore not a clean comparison of the same content delivered differently.

The useful result was operational #

Opshin’s AGENTS.md says that the full test suite takes more than 20 minutes. Without that warning, Claude ran the whole suite an average of 3.67 times per cell. With always-on context it ran 2.44 times; with selective context, 1.67. Average runtime fell from 2,689 seconds to 2,066 and 2,032 seconds—about a 24% reduction—with no corresponding correctness improvement.

This is good evidence for a concrete kind of instruction: tell the agent the cost of an action and give it a cheaper correct path. It is not a general proof of faster execution. The analysis was exploratory, covered Claude on one repository, and was underpowered at five tasks. Codex’s duration was flat, and another repository moved slightly in the opposite direction.

The careful conclusion is:

A repository instruction file may improve how an agent works even when it does not improve what the agent can solve.

The broader evidence is mixed #

Two earlier 2026 studies reached different efficiency results:

• On the Impact of AGENTS.md Files studied 10 repositories and 124 pull requests. The presence of AGENTS.md was associated with 28.64% lower median runtime and 16.58% fewer output tokens, with comparable completion behavior.
• Evaluating AGENTS.md tested generated and developer-written files across agents and models. It found no general improvement in task success and more than 20% higher inference cost on average, although agents did follow non-standard instructions.

The new two-agent paper suggests that different injection mechanics and agent-specific task difficulty could explain the contradiction. That is a hypothesis, not a settled reconciliation. Across the three papers, the most defensible practice is to measure a file by the behavior it changes rather than assuming that more context is better.

What belongs in a useful context file #

Exact commands and the fast path #

Give commands that are ready to run, including the correct working directory and useful flags. Distinguish the targeted check from the expensive final suite:

## Verification

- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.

“Run the tests” adds little. Naming the right command, cost, and order removes guesswork.

Boundaries with a reason or safe alternative #

Record non-obvious areas the agent should not modify directly:

## Boundaries

- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.

A safe path is more useful than a prohibition alone.

Repository-specific invariants #

Include conventions that are important, surprising, and not mechanically enforced. Examples include an unusual error-mapping rule, a compatibility requirement that tests do not cover, or the one service that must use a different command.

Put service-specific facts in a nested instruction file or path-scoped rule. Loading frontend details into every backend task spends context and increases the chance of conflicts.

Recurring mistakes, not hypothetical ones #

Add a rule when an agent repeats the same costly mistake or a review catches a fact it could not reasonably infer. Remove the rule when the repository or tooling makes it obsolete. This keeps the file grounded in observed failures instead of accumulating speculative advice.

What to leave out #

• Generic personas: “You are a senior engineer” was not directly evaluated by these studies, but it does not provide a verifiable action or repository fact.
• Vague ideals: “Follow SOLID” or “write clean code” leaves the agent to infer the same design decision it was already going to make.
• A second README: describe only structure that is surprising or affects where a change belongs.
• Complete dependency inventories: the manifest is more current and easier for the agent to inspect.
• One-off task requirements: keep them in the task prompt so they do not influence unrelated sessions.
• Rules tooling can enforce: formatters, type checks, tests, hooks, and CI are stronger than prose for deterministic requirements.
• Secrets or personal credentials: an instruction file is ordinary project context, not a secret store.

A compact starting template #

# Repository instructions

## Fast path

- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)

## Verification

- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.

## Boundaries

- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.

## Known traps

- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.

Replace every example with a fact from the real repository. A ten-line accurate file is better than a comprehensive template filled with generic defaults.

Choose the smallest durable mechanism #

For cross-agent installation and maintenance of on-demand procedures, see the practical skills.sh guide. An instruction file should not become a substitute for every other control surface.

Evaluate the file in your own repository #

Research averages cannot tell you whether one instruction helps your codebase. Pick a repeatable task where the instruction should change behavior, then run several trials with and without it using the same agent and model version. Track:

• hidden or independently written test results;
• targeted and full-suite invocations;
• elapsed time and token use;
• unnecessary file changes and permission requests;
• whether the agent followed the specific rule.

Keep an instruction when it improves a result or prevents measurable waste. Rewrite or remove it when it is ignored, duplicated, stale, or merely makes the prompt longer. The aim is not the perfect context file; it is a small set of repository facts that reliably changes work for the better.