AGENTS.md vs CLAUDE.md
Vintage: 2026-08. Instruction-file standard fight as of 25 Aug 2026 in 2026-08-27-best-agent-harnesses-for-programming. Claude Code’s promised AGENTS.md support was “working on it,” not fetched as shipped.
AGENTS.md vs CLAUDE.md
One-line summary: Two competing instruction-file standards for programming agents — OpenAI documents AGENTS.md as the instruction chain; Anthropic still ships CLAUDE.md as native. The 25 Aug 2026 X fight is primary (Tobi vs Thariq), not a settled industry standard.
The insight
This is a standard question, not the same as “should a team keep a living CLAUDE.md?” (claude-md-team-knowledge-base). The process claim (update the file when the agent errs) can survive either filename. The contested claim is which filename a cross-tool repo should commit, and whether one model family can read the other’s file without a translation layer.
Evidence
- From 2026-08-27-best-agent-harnesses-for-programming: Codex official AGENTS.md is the instruction chain — global
~/.codex, then repo-root-to-cwd walk, override files, 32 KiB default cap, fallback filenames (project_doc_fallback_filenames). - From the same source: Claude Code official is
CLAUDE.md/.claude/skills; dynamic workflows mine sessions back intoCLAUDE.md. - From the same source (X, primary, 2026-08-25): Shopify CEO Tobi Lütke threatened to ban Claude Code until it reads
AGENTS.md. - From the same source (X, primary, 2026-08-25): Claude Code staff Thariq Shihipar said they will add AGENTS.md / system-prompt hackability, but argued model families are not interchangeable so Claude.md stays default.
- From the same source (X, discourse, 2026-08-25): Kun Chen — “industry already has a standard.” Discourse, not a lab measurement.
- From the same source: Claude Code’s promised AGENTS.md support was “working on it” as of 25 Aug 2026, not fetched as shipped.
This thread already had a weaker AGENTS.md signal: claude-md-team-knowledge-base notes a reply-commenter variant (AGENTS.md for agent behaviors) and Cursor Cloud Agent best-practices using agents.md + skills. Those are process/filename color, not the official Codex instruction-chain spec.
Contradictions / tensions
- Official standard vs native default. OpenAI documents AGENTS.md as the instruction standard. Anthropic still ships CLAUDE.md as native. Both can be true at once; neither source fetched a shipped Claude Code AGENTS.md reader.
- Interchangeability. Thariq’s load-bearing argument is that model families are not interchangeable, so a shared filename would still need a Claude-shaped body. Tobi’s load-bearing demand is that Claude Code read the file the rest of the industry already writes. Unresolved.
- This thread’s own repo. Brain already carries both
AGENTS.md(Grok) andClaude.md(Claude Code compat). That is local practice, not evidence that the industry fight is settled. Do not treat vault conventions as a source.
Open questions
- Did Claude Code ship AGENTS.md / fallback-filename support after 25 Aug 2026?
- If it ships, does Claude treat AGENTS.md as a first-class walk or as an alias that still prefers CLAUDE.md?
- Does a shared filename without a shared body actually port instructions across model families?