AGENTS.md vs CLAUDE.md vs spec.md: what goes where, and what the research says

Published 23 October 2026

AGENTS.md and CLAUDE.md do the same job: standing instructions a coding agent reads at the start of every session — build and test commands, conventions it cannot guess, rules learned from its mistakes. AGENTS.md is the shared name that Codex, Copilot, Cursor, Kiro and many others read; CLAUDE.md is Claude Code’s own, and Claude Code now reads AGENTS.md too when there is no CLAUDE.md. A spec.md is a different thing: one change — what it must do and why — read while that change is worked on. The research is sobering: these files do not reliably make agents succeed more often, they add cost, and they grow and go stale. What helps is a short, hand-written file of what the agent would otherwise get wrong. Below is which tool reads which file, how to keep one file for all of them, what goes where, what the studies found, and how to keep the file from rotting.

Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong.

— Addy Osmani, Agent Harness Engineering, April 2026

AGENTS.md vs CLAUDE.md: the short answer

The AGENTS.md site describes the format as “used by over 60k open-source projects” and has no required fields: “AGENTS.md is just standard Markdown” (agents.md). Anthropic describes CLAUDE.md files as “markdown files that give Claude persistent instructions for a project” (Claude Code documentation).

Which tool reads which file

As each tool’s documentation described it on 23 October 2026:

Most of them also read nested files, so a subfolder can have its own. When two disagree, the AGENTS.md site’s rule is: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” Codex documents the same order: “Files closer to your current directory override earlier guidance because they appear later in the combined prompt” (OpenAI).

One file for every tool

If your team uses more than one agent, keep the instructions in AGENTS.md and let Claude Code read them through a short CLAUDE.md. The pattern from Anthropic’s documentation, with anything specific to Claude Code below the import:

@AGENTS.md

## Claude Code

Use plan mode for changes under
`src/billing/`.

A symlink works too (ln -s AGENTS.md CLAUDE.md), with two catches the documentation lists: Claude Code’s edit tools refuse to write through the link, and on Windows a committed symlink can arrive as a one-line text file. Teams that switch agents often go further. One commenter: “AGENTS.md by default across the codebase, a script makes sure CLAUDE.md symlink present wherever there’s an AGENTS.md file” (Hacker News, 2026).

The trap is a project with both files and no import: Claude Code reads CLAUDE.md only, and the AGENTS.md everyone else maintains is silently left out.

What goes where: AGENTS.md, CLAUDE.md or the spec

Anthropic’s rule for CLAUDE.md: “Keep it to facts Claude should hold in every session: build commands, conventions, project layout, ‘always do X’ rules.” And when to add a line: when “Claude makes the same mistake a second time.” A feature’s requirements are not facts for every session, so they go in the spec.

OpenAI’s team describes the same split from the other side: “So instead of treating AGENTS.md as the encyclopedia, we treat it as the table of contents”, pointing to product specs and execution plans kept in the repository (OpenAI, vendor, February 2026).

There is a third kind of knowledge that fits neither file: why a rule exists. One commenter’s example: “‘Never use GraphQL for this service’ is a useful rule to have in CLAUDE.md.” What the file does not hold is that GraphQL was tried and dropped, and why. “The agent follows the rule. It can’t tell when the rule is no longer load-bearing” (Hacker News, 2026). That belongs in a decision log, with the rule pointing to it.

Do these files help? What the research says

They are how most teams configure an agent. Of 2,853 repositories that configure an AI coding tool in any way: “We identified 4,768 Context Files across 2,586 of the 2,853 repositories in our sample (90.6%)”. CLAUDE.md made up 34.4% of them, AGENTS.md 31.6% and copilot-instructions.md 29.2% (Galster et al., 2026, preprint).

What is in them is mostly how to work, rarely what must hold. Across 2,303 context files, most described testing, implementation details and architecture, but “non-functional requirements such as security (14.8%) and performance (14.5%) are rarely specified” (Chatlatanagulchai et al., TOSEM).

They do not reliably raise success, and they cost more. The most careful test so far, with four agents: “Surprisingly, we find that providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average.” Agents do obey them: “while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful.” Developer-written files did slightly better than generated ones, and the authors’ advice on the generated kind is blunt: “We therefore suggest omitting LLM-generated context files for the time being” (Gloaguen et al., 2026, preprint).

The evidence is mixed, not negative. A smaller study found an AGENTS.md “associated with a lower median runtime (Δ28.64%) and reduced output token consumption (Δ16.58%)”, though it did not check whether the code was correct (Lulla et al., 2026). Across 441 repositories, those with committed AI configuration showed about half the growth in code complexity of those without (+27% against +53%), an observational result (Denisov-Blanch et al., ASE 2026). And the Thoughtworks Technology Radar, in its April 2026 entry on “agent instruction bloat”, notes that “research suggests that hand-written versions are often more effective than LLM-generated ones” (Thoughtworks).

Practitioners report both sides. One commenter with a legacy codebase of about 300,000 lines: “It just prevents hallucinations and coerces the AI to use existing files and APIs instead of inventing them” (Hacker News, 2026). Another, in a thread about an article titled “Your AGENTS.md file doesn’t do anything”: “I added one when it kept making the same mistake and using things from the wrong library version making compiler errors” (Hacker News, 2026).

What the evidence supports: a short file, written by a person, holding what the agent cannot work out from the code and would otherwise get wrong. Not a generated overview of the repository.

Why these files go stale

They grow and are rarely pruned: “The evolution of Agent context files is driven by small, incremental additions, while deletions are minimal” (Chatlatanagulchai et al.). Or they are written once and never touched: in the 441-repository study, “73.8% of artifacts are committed once and never modified.” Either way they fall behind the code. Across AI configuration files in 356 repositories, 23.0% of the repositories had references to code that no longer exists, and “When stale, such descriptions can degrade AI assistance without any visible error” (Treude and Baltes, 2026, preprint).

Generated files start that way. One commenter, on files written by the tools’ /init commands: “Those often seem to generate a snapshot of the current state of the codebase that to me seem to be just begging to get out of date” (Hacker News, 2025).

And none of them is enforced. Anthropic’s documentation: “Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” One commenter keeps a deliberately short CLAUDE.md with a rule about git commits, and “Claude will very regularly ignore this rule” (Hacker News, 2026).

How to keep the file useful

1. Write it by hand, starting empty, and add a line when the agent gets something wrong twice.
2. Keep it short. Anthropic’s target: “under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” Cursor’s advice is to keep a rule under 500 lines.
3. Leave out what the agent can see for itself — a tour of the folders, the stack it can read from the code.
4. Point to the specs and the decisions instead of copying them in.
5. Review it in pull requests like code, and delete lines that no longer hold. Claude Code’s /doctor prompt-audit looks for outdated and conflicting instructions.
6. Enforce what must always hold with a hook, a linter or a CI check, not a sentence.

A short example, every line of which earns its place:

# AGENTS.md

## Commands
- Install: uv sync
- Test: just test
- Lint and types: just check

## Conventions
- Money is integer cents, never floats.
- API dates are ISO 8601, in UTC.

## Specs
- One spec per change, in specs/.
- Read the spec named in the task
  before planning.
- If the work shows the spec is wrong,
  stop and say so.

## Learned the hard way
- Use the payment sandbox in
  integration tests; never mock it.

How the spec side of this works in Claude Code — the files, plan mode, a fresh session — is in spec-driven development with Claude Code.

Where Specroot fits

This is the problem Specroot works on: the part that does not belong in AGENTS.md or CLAUDE.md — what each change must do, why, and who agreed — kept current and readable by the people who have to agree. Specroot for teams using AI coding agents.