# AGENTS.md in Claude Code: The Real Signal Is the Harness, Not the Compat Fix
On September 19, Thariq Shihipar, an engineer on the Claude Code team, posted an announcement that passed one million views within an hour. Starting with version 2.1.277, if your project has no CLAUDE.md, Claude Code will look for and read AGENTS.md instead.
Most takes stopped at "Anthropic finally caved." True, but it misses the point.
The concession is the surface. Underneath, something structural happened: **competition among coding agents is shifting from the model layer to the harness layer, and the first cross-vendor standardization in this space did not happen on models — it happened on instructions.**
Whoever controls how project context gets read controls the first gate a developer passes through when switching tools. That gate was just dismantled.
## The Thirteen-Month Standoff
Start with the basics.
CLAUDE.md and AGENTS.md are, functionally, the same object: a file sitting in the repo that tells the agent how to build, how to run tests, and what conventions to follow. (Apologies — a project brief for AI agents.)
The difference is who recognizes it. CLAUDE.md is Anthropic's home turf. AGENTS.md is the open format OpenAI introduced in August 2025. Codex uses it. So do Cursor, GitHub Copilot, Gemini CLI, and Devin. Today, more than 60,000 open-source projects have adopted it.
In December, OpenAI donated AGENTS.md to the Agent AI Foundation (AAIF), a new project under the Linux Foundation. Here is the ironic part: Anthropic is a platinum member of that foundation — it donated its own MCP protocol there too. Two companies sit on the same standards body while their flagship coding tools refuse to read each other's instruction files.
The cost of that standoff was real. The GitHub issue requesting AGENTS.md support had been open since August 2025, accumulating over 5,200 upvotes and 300+ comments — the single most-upvoted feature request in the Claude Code repository, four times the count of the runner-up.
Developers improvised workarounds: symlinking CLAUDE.md to AGENTS.md, writing `@AGENTS.md` inside CLAUDE.md as an import, or hooking session startup to print the file's contents into the context. AI can write code for humans, yet humans spent a year managing file compatibility on the AI's behalf.
Shopify CEO Tobi Lütke turned this into an ultimatum: he considered banning Claude Code internally unless it learned to read AGENTS.md and .agents/skills. He called the ongoing cross-tool sync burden a "complexity tax" — a tax teams pay for vendors' turf wars.
## Why Anthropic Guarded CLAUDE.md
Not mere stubbornness.
Thariq had previously explained the rationale: model families behave differently, and system prompts materially affect performance. Claude models have specific preferences for how skills, system prompts, and CLAUDE.md are organized. Project instructions, skill files, and the system prompt together form the context an agent works from — this is Anthropic's context engineering playbook, and model-specific design genuinely improves the experience.
In other words, CLAUDE.md was part of the moat: define the format context flows through, and anyone migrating to another harness must rewrite their conventions.
Why give it up now? Because the moat was no longer defensible — and the cost of holding it was rising.
Indefensible, because teams do not use one tool. One developer runs Claude Code, another Codex, a third Cursor. The same repo ends up with two nearly identical instruction files; forget to sync one, and the AI follows stale rules. When 60,000 open-source projects recognize AGENTS.md, refusing it stops being "protecting our ecosystem" and becomes "punishing our users."
Rising cost is hidden in the second layer of this announcement — mods.
## The Real Protagonist Is Mods, Not AGENTS.md
Thariq posted a second message that carries far more information.
Mods, he said, are Anthropic's upcoming customization mechanism for modifying Claude Code's own runtime framework — the harness. AGENTS.md support itself was built as a mod. It is the first built-in mod, with source code published in the official repository under `mods/agents-md`. Going forward, developers can build their own versions of how project instructions get read.
Read that literally: **what Claude Code reads, and how, is no longer decided by Anthropic alone.**
Seen this way, AGENTS.md compatibility is the demo, and mods are the product announcement. Anthropic is telling developers, in its own voice: key parts of the harness are now pluggable.
This is not an isolated move. A month earlier, DeepSeek open-sourced its Harness developer preview under the slogan "Everything is a plugin" — models, tools, skills, sessions, sandboxes, and UI all decomposed into pluggable components, capable of orchestrating Claude Code and Codex as sub-agents. It collected 229,000 GitHub stars.
The two routes differ. DeepSeek Harness builds from scratch: on its Cordis kernel, the whole system is a collection of plugins, including the interface — maximum freedom, steep learning curve. Claude Code's mods cut windows into a finished product: without dismantling the shell, you insert your own logic at specific points.
One builds with blocks from zero; the other adds aftermarket parts to a production car. Different trade-offs, same direction: **the runtime framework of coding agents is ceasing to be a black box.**
## A Framework: The Three-Layer Stack of Agent Competition
Put the last two years of coding-agent competition together and a framework emerges. Competition happens on three layers, and the moat strength of each is completely different.
**Layer one is the model.** Gaps in coding, reasoning, and agentic ability are converging fast. Benchmark scores increasingly fail to function as moats.
**Layer two is the instructions — project context.** This layer just finished standardizing. AGENTS.md is donated to the Linux Foundation, adopted by 60,000+ projects, and now read by Claude Code. The "README for agents" has become repository infrastructure, with the same status as .gitignore. Nobody can lock anyone in with a file format anymore.
**Layer three is the chassis — the harness.** The real battleground lives here: how the execution loop is designed, how tools are orchestrated, how context is managed, and — the newest dimension — **modifiability**. A closed harness is a product; a modifiable harness is a platform. Products retain users through habit; platforms retain users through ecosystems.
Reread the news through this lens: Anthropic abandoned the lock on the instructions layer because that layer no longer generates value — only complexity tax. Simultaneously, it used mods to claim the high ground on layer three. Rather than defend a format destined to fall, it became the first to declare "my chassis can be modified."
History offers a precedent. The editor wars ran for a decade, and what ended them was not one editor winning — it was the Language Server Protocol (LSP) decoupling editors from language support. After LSP, editors competed on experience instead of language lock-in. AGENTS.md is replaying the LSP script at the instructions layer, and plugin-ization is replaying it at the chassis layer.
As switching costs drop, the question shifts from "Claude Code or Codex?" to "which chassis works better — and which one can I modify?" That is a stress test for every vendor.
## What You Should Do
**If you manage an engineering team:** make AGENTS.md the single source of truth for project instructions and delete duplicate files. The complexity tax you eliminate is real engineering time. Keep one item on the books: `.agents/skills` and `.claude/skills` remain separate directories — compatibility is not unification, and the last mile is unfinished.
**If you are a hands-on developer:** retire the symlinks and `@AGENTS.md` imports. After upgrading to 2.1.277, use /config to choose between fallback reading and loading both files. Better yet, read the source of `mods/agents-md` — the hook mechanism and lifecycle of the first official mod is Anthropic's blueprint for extensibility.
**If you build agent tooling:** stop inventing proprietary instruction formats. Adopt AGENTS.md and place your engineering bets on layer three — execution loop quality, context management, and extension mechanisms. The question of the future is no longer "which models do you support?" but "can you be modified?"
One instruction file, four workarounds, thirteen months of awkwardness — resolved into a single consensus: context is shared infrastructure, not anyone's moat.
The real war is just opening, on the chassis.
---
Sources: Claude Code 2.1.277 changelog (code.claude.com/docs/en/changelog); Thariq Shihipar (@trq212) posts on X; mods/agents-md source in anthropics/claude-code; AGENTS.md donation to Linux Foundation's AAIF; reporting by 新智元 and 机器之心 (via 36Kr).