AGENTS.md Spec — Complete Guide
OpenAI · Google · Cursor · Factory joint proposal · CLAUDE.md compatible · real-repo examples · As of 2026-10-07, Claude Code 2.1.277+ reads AGENTS.md in projects without a CLAUDE.md
Why AGENTS.md Was Needed
Through early 2025, every AI coding tool had its own project memory format — Cursor used .cursorrules, Claude Code used CLAUDE.md, Codex used instructions.md, Aider used .aider.conf.yml. Switching tools meant rewriting your project knowledge. In August 2025, OpenAI, Google, Cursor, Factory and others jointly released AGENTS.md as a cross-vendor standard so one config file works with any compatible agent.
The Five Core Sections
AGENTS.md defines five standardized sections separated by Markdown H2 headings, compatible with every Markdown editor:
Identity: agent identity, role, response language
Capabilities: capability declarations, tool preferences, model versions
Tools: available tool list, permission scope, external API config
Memory: project context, conventions, glossary, past decisions
Constraints: forbidden behaviors, safety rules, compliance
Interop with CLAUDE.md and .cursorrules
AGENTS.md is not a replacement — it's the greatest common divisor across tools. Claude Code's documented behavior (checked 2026-10-07) is either/or by default: it reads AGENTS.md when there is no CLAUDE.md, and only CLAUDE.md when both exist. Cursor reads AGENTS.md natively since 1.2. Codex CLI looks for AGENTS.md first, falling back to instructions.md.
Toolchain Support Today
CursorCursor 1.2+: native support, AGENTS.md takes precedence over .cursorrules
Claude CodeClaude Code: reads it natively since 2.1.277 (released 2026-09-18); the changelog says “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead”. The default is either/or: with a CLAUDE.md in the working directory or above, only CLAUDE.md loads; set Project instructions in /config to read both. Since 2.1.281 (2026-09-23) this also works behind LLM gateways (checked 2026-10-07).
Codex CLICodex CLI: looks for AGENTS.md by default since 2026-02, across all OpenAI tools
AiderAider: experimental support since 0.65, enabled via --agents-md
Five Common Anti-Patterns
1) Stuffing all historical decisions into Memory until the file balloons past 10 KB; 2) Writing Identity as marketing copy instead of executable directives; 3) Constraints listing abstract principles rather than concrete forbidden behaviors; 4) Stale Tools lists that no one cleaned up; 5) Mixing it with .gitignore — AGENTS.md must be in version control so the team shares it.
Running Claude Code with AGENTS.md from Restricted Networks
A common question: "I'm a developer in mainland China and Claude Code keeps timing out on my AGENTS.md project — what now?" This is a network reachability issue unrelated to the spec itself. Options: subscribe directly with Anthropic (best on stable overseas networks); use a branded API subscription service like QCode.cc (China-optimized access + unified billing + one key for four models); or build your own enterprise gateway (long lead time).
Run Your First AGENTS.md Project on QCode.cc
Claude Fable 5 · GPT-5.5 · Codex · Gemini 2.5 Pro — one subscription, four tools
Create a QCode account
One key across Claude, GPT and Chinese models, billed per token — live rates on /models.