AGENTS.md – Open format for guiding coding agents

Who Should Read

Developers using AI coding agents (Cursor, Copilot, Codex, Claude Code, etc.) in production who want to help agents better understand project context.

Core Mechanics

• AGENTS.md is a markdown file that tells AI coding agents about a project's build commands, test methods, code style rules, etc. While README.md is for human onboarding, AGENTS.md is for agent onboarding.
• 20+ coding agents/tools already support AGENTS.md including OpenAI Codex, Google Jules, Cursor, Windsurf, Aider, GitHub Copilot, Gemini CLI, Factory, Zed, and Warp. A single file applying to multiple agents is the key selling point.
• Usage is simple: create AGENTS.md at the project root with project overview, build/test commands, code style, PR rules, etc. No required fields or schema — just markdown.
• In monorepos, each subproject can have its own AGENTS.md. Agents read the nearest file in the directory tree, enabling per-package custom instructions. OpenAI's main repo reportedly has 88 AGENTS.md files.
• The Agentic AI Foundation under the Linux Foundation now officially stewards this format. It's an open format built collaboratively by OpenAI, Google, Cursor, Amp, Factory, and others.
• Over 60,000 open-source projects on GitHub already use AGENTS.md, including large projects like Apache Airflow (4,215 lines) and Temporal SDK (122 lines).
• It's more of a filename convention than a true standard. There's no enforced structure — you can write anything in the markdown. This is both its strength and limitation.

Evidence

• Currently Claude Code uses CLAUDE.md, Cursor uses .cursorrules, Windsurf uses .windsurfrules — each agent has its own file, so unification under a single AGENTS.md isn't actually happening. Some use tools like ruler (github.com/intellectronica/ruler) to auto-generate multiple formats.
• An ironic reaction was common: 'People wouldn't write docs for humans, but they write them for robots.' Ultimately, organizing docs for AI benefits humans too — the 'ergonomic handles' analogy resonated.
• Experience shared that splitting into a folder structure (.agents/index.md + auth.md + testing.md) is far better than one giant markdown. Reduces token waste and enables selective context loading.
• Fundamental skepticism: 'Wasn't the promise of LLMs that agents understand codebases without special guides?' Some argue good human-centered docs should be sufficient, while others shared using AST+RAG hybrid search for 5,000+ repos as a more effective approach.
• Anthropic/Claude was noted as missing from the support list. Claude Code uses its own CLAUDE.md, with symlinks (AGENTS.md → CLAUDE.md) mentioned as a workaround.

How to Apply

• If you maintain an open-source project, add AGENTS.md at the project root with build commands, test instructions, code style rules, and PR conventions to improve quality when external contributors work with AI agents.
• When using multiple agents (Claude Code + Cursor, etc.), write AGENTS.md as the master file then create symlinks: ln -s AGENTS.md CLAUDE.md, ln -s AGENTS.md .cursorrules. Or use the ruler tool (github.com/intellectronica/ruler) for auto-generation.
• In monorepos with different build/test methods per package, place separate AGENTS.md files in each package directory. Agents read the nearest file when working in that directory, reducing unnecessary context loading.
• If AGENTS.md gets too large, consider switching to a .agents/ folder structure. Put the main guide in index.md and split into auth.md, testing.md, data_layer.md, etc. for better token efficiency and maintainability.

Code Example

# AGENTS.md Example

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- Fix any test or type errors until the whole suite is green
- Add or update tests for the code you change

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

# Supporting multiple agents with symbolic links
$ ln -s AGENTS.md CLAUDE.md
$ ln -s AGENTS.md .cursorrules

Terminology

Related Resources

• https://agents.md/
• https://github.com/anthropics/claude-code/blob/main/CLAUDE.md
• https://agent-rules.org/
• https://github.com/intellectronica/ruler
• https://github.com/sutt/agro