CLAUDE.md or AGENTS.md? Claude Code now reads AGENTS.md, and Anthropic says new projects can skip both

If your repository carries both a CLAUDE.md and an AGENTS.md with nearly the same content, plus a script to keep them in sync, you can stop. Anthropic’s documentation says that from Claude Code v2.1.277, when no CLAUDE.md exists in the working directory or above it, Claude Code reads AGENTS.md directly. On the September 29 episode of the Latent Space podcast, Claude Code team member Thariq Shihipar went further: starting a new project without a CLAUDE.md may now be the better default.

Facts checked October 6, 2026. The loading rules come from the Claude Code docs and the podcast quotes from Latent Space’s published transcript. A Chinese write-up of the episode headlined “never needed again” is stronger than what Thariq said, and this piece corrects that.

Key points

• Per the docs: with only an AGENTS.md, Claude reads it; with both files present, Claude reads CLAUDE.md only, unless that file imports @AGENTS.md.
• Thariq’s wording was “I think that right now it might be better to start a new project without a Claude.md”, adding rules for failure modes that repeat. He did not say static instruction files are useless.
• A paper by Gloaguen et al. (arXiv:2602.11988) found context files do not generally raise task success and raise inference cost by over 20% on average; repository overviews were the least helpful part.

Why this became an argument

The dispute began with a post by Shopify CEO Tobi Lütke on August 25, 2026. He said he was considering banning Claude Code at Shopify until it read AGENTS.md and .agents/skills. According to The New Stack, his case was scale: thousands of developers in one monorepo, using different AI coding tools, with both file types applied recursively through the directory tree. Sooner or later a directory has only one of the two, and a subset of developers works with a “lobotomy”. He called the automation Shopify built to bridge the gap a “stupid complexity tax”.

AGENTS.md is a README for coding agents. Its site says more than 60,000 open-source projects use it and lists Codex, Cursor, Gemini CLI, Windsurf and GitHub’s Copilot coding agent among compatible tools. Claude Code had read only its own CLAUDE.md; The New Stack notes that a request for recursive AGENTS.md discovery had been closed as not planned.

About six weeks later, that changed.

What Claude Code reads today

The AGENTS.md section of the official docs spells out the rules. This is the short version.

And the common cases as a table:

What is in the repo	What Claude Code reads by default
Only AGENTS.md	AGENTS.md; the session shows no CLAUDE.md found; AGENTS.md loaded
AGENTS.md and CLAUDE.md	CLAUDE.md only
CLAUDE.md containing @AGENTS.md	CLAUDE.md, with AGENTS.md pulled in by the import
AGENTS.md plus your own uncommitted CLAUDE.local.md	CLAUDE.local.md only; AGENTS.md is skipped

Source: Claude Code docs, “How Claude remembers your project”, checked October 6, 2026.

The last row is the trap: CLAUDE.local.md counts as a CLAUDE.md. To load both, set Project instructions in /config to claude-md-and-agents-md (the default is claude-md-or-agents-md). Two more edges. Before v2.1.281, some sessions (the docs cite Amazon Bedrock and sessions with telemetry disabled) read CLAUDE.md files only, so an @AGENTS.md import is still the fallback there. And an AGENTS.md loaded through the setting does not fire InstructionsLoaded hooks.

If your team also uses Codex or Cursor, the lowest-effort setup is one AGENTS.md as the single source and no duplicate CLAUDE.md. If some of your sessions cannot read it, keep a one-line CLAUDE.md that contains only @AGENTS.md.

What Thariq actually said

At about 28 minutes into the Latent Space episode (published September 29, 2026, about 1 hour 32 minutes long), host swyx asked whether CLAUDE.md is going away. Thariq said they are going to support AGENTS.md, because maintaining separate files for different models is a pain.

The rest, reconstructed from the transcript:

1. As models improve, the floor for simple tasks rises, so “in the limit” CLAUDE.md goes away.
2. “I think that right now it might be better to start a new project without a Claude.md.” That is a hedge, not a product policy.
3. If you see repeated failure modes, add them to the file.
4. Those rules are model-specific: Fable 5 might have a failure mode Fable 5.1 does not. A running log of failure modes will probably over-constrain Claude.

Compare that with the headline that traveled in Chinese-language press. Compressing “might be better to start without one” into “never needed again” drops two conditions: rules are triggered by repeated failures, and they need rechecking when the model changes. Anthropic’s own docs still teach people to write CLAUDE.md, suggest keeping each file under 200 lines, and move rules that matter for only part of a codebase into .claude/rules/. The two positions fit together: the files stay, and what is being retired is the habit of writing a long one up front.

Is there evidence for writing less?

Yes, with a narrower conclusion than the slogan. “Evaluating AGENTS.md” (Gloaguen et al., submitted February 2026, revised to v3 on September 29) tested several models and coding agents on two kinds of tasks: SWE-bench issues with LLM-generated context files, and issues from real repositories whose developers had committed their own.

Finding	What the abstract says
Success rate	Context files do not “generally improve” task success
Cost	Inference cost up by over 20% on average
Scope	Holds across LLMs, agents, generated and developer-written files
Do agents obey?	Yes, the instructions in the files are well followed
Least useful content	Repository overviews, popular and recommended by model providers
Where files help	Specifying non-standard coding practices

Source: arXiv:2602.11988 abstract, checked October 6, 2026.

The supported claim is narrow: do not write down what an agent can see by reading the code, such as directory layouts and stack introductions. Every line costs tokens and competes for attention. It does not support “instruction files never help”; the paper itself says they are useful for non-standard practices.

A three-step setup for a new project

Putting the docs, the podcast and the paper together:

1. Start with nothing. Begin work with a current model such as Opus 5.5 and watch how it actually fails in your repo, instead of guessing in advance.
2. Record only repeated failures. When the same mistake appears a second or third time, write one concrete rule: “tests run with pnpm test, not npm test”; “database migrations come from the generator, never by hand”. Write non-standard conventions, not a project tour.
3. Re-audit on every model upgrade. After switching models, delete rules one by one and rerun your tasks; add back only those that still prevent a failure. Thariq mentioned that the team just added an evals plugin for skills, so you can test whether a skill makes things better. Treat the file the same way.

The same restraint applies to prompts generally, which is the thread in the official Opus 5.5 prompting guide: cut instructions that think on the model’s behalf. For a heavyweight example of configuring Claude Code as a full engineering team, see gstack and judge how much of that your project needs.

FAQ

Do I still need both files?

Usually not. Put the content in AGENTS.md; Claude Code reads it when there is no CLAUDE.md. Add a CLAUDE.md containing @AGENTS.md only if your environment cannot read it directly (older versions or the session types the docs list).

Does “read AGENTS.md first” work?

Not reliably. The docs say Claude sees the file only if it decides to open it. Use an @AGENTS.md import instead, or delete the CLAUDE.md so Claude reads AGENTS.md directly.

Are instruction files hard rules?

No. The docs describe them as context, not enforced configuration. For “never do this under any circumstances”, use a PreToolUse hook rather than adding more sentences to the file.

Our take

For teams running several coding tools, Claude Code reading AGENTS.md natively is a real saving. The more useful part of Thariq’s remarks is a method, not a prediction: an instruction file is a patch for a model’s weak spots, and patches need re-verifying when the model changes. Treat every rule you write today as a hypothesis to review after the next model release, not as an asset.

This article drew on InfoQ’s Chinese edit of the podcast, “CLAUDE.md or AGENTS.md? Anthropic’s answer: never needed again” (October 6, 2026, WeChat).