Claude Code Adds AGENTS.md Support: The Agent-Instruction Standards War Is Over

Buried in the Claude Code v2.1.277 changelog from September 18 is an unassuming update with outsized consequences: AGENTS.md support — in a project with no CLAUDE.md, Claude Code now reads AGENTS.md instead. It looks like "recognizing one more filename." It's actually an industry-level signal: the standards war over agent instruction files is converging, and the likely winner is OpenAI's AGENTS.md.

This piece explains what AGENTS.md is, why Claude Code adopted it, and what it means for your projects.

From dialects to a lingua franca

First, the messy status quo. Over the past year, every agent tool invented its own "project manual": Claude Code read CLAUDE.md, Cursor used .cursorrules (later Rules), Windsurf had its memory, Codex read AGENTS.md. The result: one project, three tools, three instruction files saying mostly the same things — stack, conventions, common commands, directories to avoid.

OpenAI pushed AGENTS.md as an open standard in 2026: a Markdown file at the repo root telling any agent "what this project is, how it works, what the rules are," in a uniform format. Cursor and Windsurf followed; now Claude Code recognizes it too. When the most stubborn holdout (Anthropic had its own CLAUDE.md tradition) starts honoring the rival standard, the standards war is effectively over.

Note how graceful Anthropic's move is: not killing CLAUDE.md, but reading AGENTS.md only when CLAUDE.md is absent, with an override under "Project instructions" in /config. A dignified surrender — own tradition kept, industry standard honored. Nobody offended, but the direction is unmistakable.

Why this matters more than it looks

First, it lowers the cost of switching tools. Moving from Cursor to Claude Code used to start with rewriting instruction files; soon one AGENTS.md works everywhere. Tool vendors won't love it — that's one less lock-in lever. For users it's pure win: competition moves back to what actually matters — model capability, execution reliability, price.

Second, it turns "instructions" into a code asset. Once AGENTS.md is the standard, it joins README and CI config as a first-class repo citizen: reviewable, versioned, reusable across projects. Teams are already maintaining org-level AGENTS.md templates — new scaffolds ship with one, good practices accumulate. That's the leap from "personal trick" to "engineering asset."

Third, it defines the agent's first principles. The most valuable part of the AGENTS.md standard isn't the format — it's the three questions it forces you to answer: what is this project for? (context) What are the inviolable rules? (constraints) What are the common workflows? (process) Teams that can't answer don't have a file problem — the file is a mirror.

Hands-on: what a good AGENTS.md looks like

Don't write a novel. Agent attention is also a budget — the golden length for AGENTS.md is 50–150 lines. Suggested structure:

• One-line project summary: what it is, who it's for, stack keywords. Give the agent a mental model on first read.
• Iron rules (no more than 10): e.g. "all DB migrations must be reversible," "never push to main directly," "no merge under 80% test coverage." Few and hard — many rules equals no rules.
• Common commands: how to run tests, start the local env, build. Don't make the agent guess — guesses go wrong, and wrong guesses burn your tokens and time.
• Off-limits zones: which directories are generated (don't touch), which files are hand-written (don't rewrite), which operations (dropping databases, shipping releases) require asking a human first.
• Code style in three sentences: enough. Don't paste your eslint config — agents can't use long rule lists; they need usable judgments like "prefer composition over inheritance."

One anti-pattern warning: don't put "requirements" in AGENTS.md. It's a constitution, not a work order. Writing one-off asks like "add remember-me to the login page" rots the file fast. Requirements go in issues and prompts; AGENTS.md holds only long-lived truths. The test: will this rule still hold in three months? If not, don't write it.

AGENTS.md implementations compared: the devil in the details

"Everyone supports AGENTS.md" doesn't mean "everyone supports it the same way." Implementation details across the three determine how you write your file:

• Codex (native): AGENTS.md is the first-class citizen. Multi-level support — one at the root, more in subdirectories, with subdirectory files "overriding + supplementing" the root. File references inside AGENTS.md work too. Write Codex's AGENTS.md with a bold "layered" structure.
• Claude Code (compatible): reads AGENTS.md only "when CLAUDE.md is absent" — priority is CLAUDE.md > AGENTS.md. Currently whole-file reads, no subdirectory layering. If your project has both files, keep them consistent — otherwise Claude Code and Codex read different "constitutions." That's a buried landmine.
• Cursor (following): honors AGENTS.md through its Rules system, but Cursor Rules have their own "scope" concept (global/project/file-level), and AGENTS.md content gets "translated" into it. Close in practice, but when debugging note: the "effective rules" Cursor shows may not exactly match the file.

The practical conclusion: to make one AGENTS.md work across all three, write to the "lowest common denominator" — root-level single file only, generic Markdown only (headings, lists, code blocks), no vendor-specific syntax. Want advanced features (layering, references)? Accept "best on Codex, degraded elsewhere."

Migration in practice: three steps from CLAUDE.md to AGENTS.md

Already have a CLAUDE.md? Don't delete it — migrate in three steps:

Step 1: copy + rename, get running first. Copy CLAUDE.md to AGENTS.md (keep CLAUDE.md for now), run one standard task in each of the three tools, compare. This phase's goal is "verify compatibility," not "optimize."

Step 2: strip proprietary syntax, downgrade to generic. CLAUDE.md may contain Claude Code-isms (@ references, special frontmatter) — remove or rewrite them as plain language in AGENTS.md. Principle: AGENTS.md holds only "human words," never "incantations" — all three understand human words; only one understands incantations.

Step 3: delete CLAUDE.md (optional), or keep it as an "enhancement layer." Two routes: full migration — delete CLAUDE.md, one AGENTS.md everywhere, simple and clean. Dual-track — keep CLAUDE.md holding only Claude Code-specific enhancements (e.g. MCP configs), generics in AGENTS.md. My recommendation: solo projects go full migration; team projects go dual-track (someone on the team only uses Claude Code, guaranteed).

Advanced: org-level AGENTS.md templates

With 3+ projects, build an "org template": new scaffolds ship with an AGENTS.md containing your team's universal iron rules (branching strategy, testing requirements, code style in three sentences, off-limits zones). Each project's AGENTS.md = org template + project specifics.

This is undervalued: it turns "team engineering culture" into "executable code." Culture used to spread by word of mouth and code-review nagging; now it's in AGENTS.md, read by every agent on first entry. A newcomer's (human newcomers too) first onboarding step is no longer "ask around for the rules" — it's "read AGENTS.md." A good org template does half a Tech Lead's "rule-setting" job.

Maintenance advice: keep the org template in its own repo, versioned, synced to projects via git submodule or scaffolding. Template changes go through PR review — changing the template means changing the "constitution," which deserves more care than changing code.

FAQ: 5 quick questions, quick answers

Q1: Already have CLAUDE.md — need AGENTS.md too? A: depends on tool count. Claude Code only — no, CLAUDE.md suffices. Two-plus tools — yes; one AGENTS.md replaces N files to maintain.

Q2: AGENTS.md vs. README? A: README is for humans ("what this project is"); AGENTS.md is for agents ("what rules to follow working here"). README says "what"; AGENTS.md says "how." Keep both; neither replaces the other.

Q3: Passwords or secrets in AGENTS.md? A: absolutely not. It goes into git and gets read by agents — writing secrets there is "taping the key to the door." Secrets live in environment variables; AGENTS.md only notes "which env var holds the secret."

Q4: How long should AGENTS.md be? A: 50–150 lines. Under 50, key constraints are probably missing; over 150, agents won't retain it — same as unwritten. Too long? Split: generics at root, module specifics in subdirectories (Codex supports layering).

Q5: How often to update AGENTS.md? A: follow the "iron rules." Rules changed (e.g. new branching strategy)? Update same day. Rules unchanged? Review quarterly. Add it to the "project health checklist," same day as dependency upgrades.

The bottom line

Claude Code honoring AGENTS.md marks the end of an era in the agent toolchain: the "my turf, my rules" dialect age is over; the "one file works everywhere" lingua-franca age has begun. For independent builders, it's a good moment to act — spend an hour writing a 100-line AGENTS.md for your main project, run the same task in Claude Code, Codex, and Cursor, and compare. You'll find the gap between tools is far smaller than the gap between "good instructions" and "no instructions." Once the standard unifies, what gets competed on is whose "constitution" is better written. And constitution-writing is one of humanity's last remaining moats.