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:

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:

1. One-sentence project description — anchors the agent’s understanding of scope
2. Package manager — only if non-standard (e.g., pnpm, yarn)
3. Build/typecheck commands — only if non-standard

Everything else goes elsewhere via progressive disclosure.

Example Minimal AGENTS.md

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:

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.

Root example:

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.

Package example (packages/api/AGENTS.md):

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.