AGENTS.md Spec — Complete Guide
OpenAI · Google · Cursor · Factory joint proposal · CLAUDE.md compatible · real-repo examples
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 now prefers AGENTS.md with CLAUDE.md as a Claude-specific extension layer. 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 both AGENTS.md and CLAUDE.md; project-specific instructions in the latter
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 Opus 4.7 · GPT-5.5 · Codex · Gemini 2.5 Pro — one subscription, four tools