AGENTS.md is a repository-level plain text file that tells AI coding agent how to behave in your codebase — what commands to run, what patterns to follow, what to avoid. It is to AI agents what CONTRIBUTING.md is to human contributors.
What It Is
Drop an AGENTS.md file (or CLAUDE.md, .cursor/rules, .github/copilot-instructions.md — each tool has a variant) into your repository root and AI agent will read it before taking any action. It persists your team's conventions into the agent's context automatically.
OpenAI contributed the AGENTS.md specification to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025. Anthropic's Claude Code uses CLAUDE.md. The Codex cloud agent reads AGENTS.md when reviewing PRs. Cursor uses .cursor/rules. The goal is convergence on a common standard.
Why It Matters
Without it, every developer re-explains the same context to every agent, every session:
- "We use pnpm, not npm"
- "Don't modify generated files in
src/generated/" - "Always run
make lintbefore committing" - "Our API uses snake_case, not camelCase"
- "Integration tests require a running Postgres — use Docker Compose first"
With an AGENTS.md, agent know all of this automatically. More importantly, it encodes the institutional knowledge your team has built up — making AI tools immediately useful for new joiners and external contributors.
Writing an Effective CLAUDE.md
The official Claude Code best practices (April 2026) add important nuance to what belongs in a CLAUDE.md:
Structure your content in three sections (HumanLayer, 2026):
- WHAT — tech stack, project structure, what each major component does. Critical in monorepos.
- WHY — the project's purpose and reasoning behind architectural decisions
- HOW — workflow instructions: build tools, test commands, verification steps
The 300-line budget: Claude Code's system prompt already contains ~50 instructions. Frontier LLMs follow ~150–200 instructions consistently, leaving headroom for your CLAUDE.md — but not much. Target under 300 lines total; HumanLayer's own CLAUDE.md is under 60 lines. When in doubt, cut.
/init vs. manual crafting: /init generates a baseline from your project structure — useful as a starting point to prune. Some practitioners prefer fully manual construction, arguing that every line should be deliberate since CLAUDE.md is "the highest leverage point of the harness." Both approaches are valid; the delete-first approach (generate then aggressively prune) converges on the same result.
Let tools do their jobs — don't use CLAUDE.md for code style guidelines; use linters and formatters. CLAUDE.md should cover things tools can't enforce automatically.
Progressive disclosure — instead of embedding long context inline, create a agent_docs/ directory with task-specific markdown files and reference them with pointers in CLAUDE.md. This keeps the main file lean while making depth available when needed.
Include vs. Exclude:
| Include | Exclude |
|---|---|
| Bash commands Claude can't guess | Anything Claude can infer from reading the code |
| Code style rules that differ from defaults | Standard language conventions Claude already knows |
| Testing instructions and preferred test runners | Detailed API documentation (link instead) |
| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
| Common gotchas and non-obvious behaviors | Self-evident practices like "write clean code" |
The context-bloat trap: If CLAUDE.md is too long, Claude ignores portions of it — critical rules get lost in noise. Prune ruthlessly. For each line ask: "Would removing this cause Claude to make mistakes?" If not, cut it or convert it to a hook.
Tuning adherence: Add "IMPORTANT" or "YOU MUST" emphasis to rules that are frequently violated. If Claude keeps ignoring a rule, the file is probably too long — shortening it often fixes compliance better than adding emphasis.
File hierarchy — CLAUDE.md can be placed at multiple levels:
~/.claude/CLAUDE.md ← global: applies to all projects
./CLAUDE.md ← project: check into git, shared with team
./CLAUDE.local.md ← personal: gitignore this, never shared
backend/CLAUDE.md ← scoped: read for backend tasks only
Modular imports — rather than one monolithic file, import sub-files:
See @README.md for project overview and @package.json for available npm commands.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
Auto-memory — Claude Code can write its own session notes into ~/.claude/projects/<project>/memory/, accumulating learnings over time. Only the first 200 lines of MEMORY.md load by default, so keep the index lean.
Multi-tool consistency — for teams using multiple agents (Claude Code + Cursor + Copilot), use symlinks to keep CLAUDE.md and AGENTS.md in sync rather than maintaining parallel files that drift apart.
Treat CLAUDE.md like code: review it when Claude's behavior is wrong, prune when it grows stale, and commit it to git so your team benefits over time.
What to Put In It
A well-structured AGENTS.md typically covers:
# AGENTS.md
## Project Overview
TypeScript monorepo using pnpm workspaces. Backend: Node/Express. Frontend: Next.js.
## Setup
Run `make dev` to start all services. Requires Docker Desktop.
## Commands
- `pnpm test` — run unit tests
- `pnpm test:e2e` — run end-to-end tests (requires running services)
- `pnpm lint` — ESLint + Prettier check
- `make build` — production build
## Code Conventions
- Use `pnpm`, never `npm` or `yarn`
- Database migrations in `db/migrations/` — never edit existing migrations
- Generated code in `src/generated/` — never edit directly, re-run `pnpm codegen`
- API routes follow REST conventions; see `docs/api-conventions.md`
## Testing Requirements
- All new features need unit tests
- Bug fixes must include a regression test
- Minimum 80% coverage on changed files
## Do Not Touch
- `package-lock.json` — we use `pnpm-lock.yaml`
- Files in `.generated/` directories
- Environment config in production (use the config service)
## PR Guidelines
- One logical change per PR
- Squash commits before merging
- Link the issue number in the PR description
Behavioral Directives: The Other Layer
Beyond repository conventions, effective AGENTS.md files often include behavioral directives — instructions about how the agent should reason before taking action. Andrej Karpathy identified four recurring LLM pitfalls that these directives target (see the reference template):
| Principle | Directive |
|---|---|
| Think Before Coding | State assumptions explicitly; ask when uncertain; surface ambiguity before implementing |
| Simplicity First | Minimum code that solves today's problem; nothing speculative; no premature abstractions |
| Surgical Changes | Every changed line must trace to the user's request; don't refactor adjacent code |
| Goal-Driven Execution | Transform abstract tasks into verifiable criteria: "write a test reproducing the bug, then pass it" |
These directives address the reasoning layer, complementing the structural layer (commands, testing, conventions) from the GitHub 6-category analysis above. A well-rounded AGENTS.md combines both: what to do (structure, commands, conventions) and how to think (assumptions, scope, success criteria).
Note: the same research that showed human-written files outperform LLM-generated ones applies here — behavioral directives that reflect your team's actual failure modes are far more useful than generic templates.
Where Files Are Read
Most tools read multiple levels — the closest AGENTS.md to the changed file takes precedence:
repo/
├── AGENTS.md ← read for all tasks
├── backend/
│ └── AGENTS.md ← read for backend tasks, overrides root for specifics
└── frontend/
└── AGENTS.md ← read for frontend tasks
The Ecosystem of Rules Files
| Tool | File(s) Read |
|---|---|
| OpenAI Codex | AGENTS.md |
| Claude Code | CLAUDE.md, then AGENTS.md |
| Cursor | .cursor/rules/*.mdc, then AGENTS.md |
| GitHub Copilot | .github/copilot-instructions.md; AGENTS.md (since Aug 2025); .github/agents/*.md for named custom agents (since Oct 2025) |
| Windsurf | .windsurfrules, then AGENTS.md |
| Goose | AGENTS.md (native) |
| Gemini CLI | AGENTS.md |
| Aider | AGENTS.md |
| OpenHands | AGENTS.md |
Recommended strategy: put your shared, tool-agnostic conventions in AGENTS.md (works everywhere). Add CLAUDE.md for Claude-specific features like @imports and /init. Tool-specific files (.cursor/rules/) are for advanced per-tool behaviour. There's even a CLI tool called rule-porter that converts .cursor/rules/*.mdc to the equivalent AGENTS.md, CLAUDE.md, or Copilot instructions.
GitHub Copilot custom agents: GitHub extended this further with named, role-based agents stored at .github/agents/AGENT-NAME.md (released October 2025). These create callable @agent-name specialists (e.g. @test-agent, @security-agent, @docs-agent) with their own persona and constraints, composable as a team within Copilot's coding agent. This is Copilot-specific — the cross-vendor AGENTS.md in the repo root still handles universal per-repo context.
AGENTS.md vs SKILL.md: AGENTS.md is per-repository context (conventions, commands, boundaries). SKILL.md is reusable procedural knowledge packaged as a portable skill. They complement each other: AGENTS.md teaches the agent your repo, SKILL.md gives it a capability. See the SKILL.md entry on this radar.
What the Research Says
A January 2026 study (arXiv 2601.20404) analysed 10 repositories and 124 pull requests, running agents with and without an AGENTS.md file:
- 28.64% lower median runtime (98.57s → 70.34s)
- 16.58% fewer output tokens
- No degradation in task completion — results held across both mean and median, not just outliers
The caveat: a separate study found that LLM-generated AGENTS.md files slightly reduced task success while increasing cost by 23%, whereas human-written files improved success by ~4%. Write it yourself; don't let an agent write it for you.
A GitHub Engineering analysis of 2,500+ agent instruction files (Matt Nigh, November 2025) identified six categories that consistently improve agent performance:
| Category | What to Include |
|---|---|
| Commands | Executable commands with all flags — npm test, pytest -v, npm run build. Include flags and options, not just tool names. Put these early — agents reference them often. |
| Testing | Framework, file locations, how to run, coverage expectations, what requires infra |
| Project structure | Which directories matter, which to ignore (generated, vendor, etc.) |
| Code style | One real code snippet beats three paragraphs describing it. Show what good output looks like. |
| Git workflow | Branch naming, commit conventions, PR rules, squash/rebase preference |
| Boundaries | Use the three-tier model: ✅ always do / ⚠️ ask first / 🚫 never do |
On specificity — the most common failure is vagueness. Per the analysis: "You are a helpful coding assistant" doesn't work. "You are a test engineer who writes tests for React components, follows these examples, and never modifies source code" does. Similarly: "React 18 with TypeScript, Vite, and Tailwind CSS" not "React project."
Three-tier boundary model:
- ✅ Always do: safe, reversible — write to
src/andtests/, run tests before commits, follow naming conventions - ⚠️ Ask first: significant changes — adding dependencies, modifying DB schema, changing CI/CD config
- 🚫 Never do: destructive or irreversible — commit secrets, edit
node_modules/, push directly tomain
Iteration over upfront planning: start with just agent name, description, and persona. Add detail when the agent makes mistakes. Don't plan the perfect file upfront.
Implementation Patterns by Project Size
Three patterns that emerge from real-world adoption:
Small/medium projects (< 100K LoC) — AGENTS.md only. Works across Codex, Cursor, Gemini CLI, and Claude Code. Lower maintenance burden, easy for new contributors.
Claude Code–centric large projects — CLAUDE.md as primary (detailed step-by-step workflows, Claude-specific features) + AGENTS.md as fallback for other tools. Both files live at the repo root.
Multi-AI + multi-team — AGENTS.md as the base with role-specific sections (Frontend Developer, Backend Developer, QA), supplemented by tool-specific files (.cursor/rules/, .github/copilot-instructions.md). For projects over 100K lines, extend with domain-specific files:
project/
├── AGENTS.md ← top-level rules
└── docs/
├── frontend.md ← frontend team rules (AGENTS.md format)
├── backend.md ← backend team rules
└── devops.md ← DevOps rules
Incremental adoption strategy: don't write the complete file upfront.
- Day one: 5–10 critical rules and build/test commands
- After one month: add common mistakes and how to fix them
- After six months: role definitions, step-by-step workflows, troubleshooting reference (30–50 items)
Adoption at Scale
As of early 2026, AGENTS.md has been adopted by 60,000+ open-source projects (source: OpenAI AGENTS.md announcement). The arXiv data quantifies what teams have observed anecdotally: a well-written AGENTS.md makes agents measurably faster and cheaper — but the file must be human-written to work well.
The Linux Foundation AAIF
AGENTS.md, MCP, and goose are the three founding projects of the Linux Foundation's Agentic AI Foundation (AAIF), formed December 2025. The AAIF's Platinum members include:
AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI
Gold members include: Adyen, Docker, IBM, JetBrains, Salesforce, SAP, Shopify, Snowflake, Temporal, Twilio, and more.
Silver members include: Hugging Face, Uber, Zapier, Zed, Pydantic, LanceDB, and more.
This membership list is a strong signal that AGENTS.md is not a niche convention — it has the backing of the companies that define the industry.
Key Characteristics
| Property | Value |
|---|---|
| Type | Convention / file-based standard |
| Effort to adopt | Low — write once, benefits all agent |
| Governed by | Linux Foundation AAIF (AGENTS.md spec) |
| Related tools | Claude Code, Codex, Cursor, Goose, Windsurf |
| Spec governed by | aaif.io |
| Introduced with | OpenAI Codex announcement |