AGENTS.md Guide
AGENTS.md is a markdown file checked into Git that customizes how AI coding agents behave in a repository. It sits at the top of the conversation history, below the system prompt. Claude Code uses CLAUDE.md instead — symlink between them:
bash
ln -s AGENTS.md CLAUDE.md
Core Principle: Minimize Token Cost
Every token in AGENTS.md loads on every single request, regardless of relevance. Frontier LLMs can follow ~150-200 instructions consistently. Keep the file as small as possible.
What Belongs in Root AGENTS.md
Only include what is relevant to every single task in the repo:
- One-sentence project description — anchors the agent's understanding of scope
- Package manager — only if non-standard (e.g., pnpm, yarn)
- Build/typecheck commands — only if non-standard
Everything else goes elsewhere via progressive disclosure.
Example Minimal AGENTS.md
markdown
This is a React component library for accessible data visualization.
This project uses pnpm workspaces.
Progressive Disclosure
Point the agent to other resources instead of inlining everything. Agents navigate documentation hierarchies efficiently.
Move domain-specific rules to separate files:
markdown
For TypeScript conventions, see docs/TYPESCRIPT.md
Nest references (keep one level deep from root):
docs/
├── TYPESCRIPT.md → references TESTING.md
├── TESTING.md → references specific test runners
└── BUILD.md → references esbuild configuration
External docs (Prisma, Next.js, etc.) can also be linked.
Monorepo Strategy
Place AGENTS.md files in subdirectories — they merge with root level.
| Level | Content |
|---|
| Root | Monorepo purpose, navigation, shared tools |
| Package | Package purpose, specific tech stack, local conventions |
Root example:
markdown
This is a monorepo containing web services and CLI tools.
Use pnpm workspaces to manage dependencies.
See each package's AGENTS.md for specific guidelines.
markdown
This package is a Node.js GraphQL API using Prisma.
Follow docs/API_CONVENTIONS.md for API design patterns.
Anti-Patterns to Avoid
- Documenting file paths — paths change constantly and poison context when stale; describe capabilities and project shape instead
- Auto-generated AGENTS.md — prioritizes comprehensiveness over restraint; never use initialization scripts to generate these
- Accumulating rules reactively — adding a rule every time the agent misbehaves creates contradictions and a "ball of mud"
- Redundant instructions — don't tell the agent things it already knows (e.g., "write clean code")
- Vague instructions — not actionable; wastes tokens
- Stale documentation — especially dangerous for agents that read docs on every request; domain concepts are safer to document than file paths
Refactoring a Bloated AGENTS.md
When the user wants to refactor an existing AGENTS.md, follow the process in references/refactoring.md.