AGENTS.md Best Practices

AGENTS.md is an open convention (agents.md): a markdown file at your repo root that agents read before doing anything. It's supported natively by Codex CLI, Grok Build, Gemini CLI, Cursor, and most modern runners. Claude Code reads CLAUDE.md — point it at the same file with a one-line import: @AGENTS.md.

Runners merge these files from the git root down to your current directory, so the nearest file wins for nested folders. (Grok Build also honors an AGENTS.override.md per directory for local-only tweaks.)

It is the highest-leverage file in any agent-powered project. Ten minutes writing it saves hours of repeated explanation and wrong-convention rework.

What actually belongs in it

The test for every line: "Would the agent do the wrong thing without this?" Project facts the agent can't discover, commands it would otherwise guess, and rules you'd otherwise repeat. Not marketing copy, not obvious advice.

# AGENTS.md

## Project
One paragraph: what this is, the stack, the package manager.

## Commands
- Dev: pnpm dev
- Test: pnpm test (single file: pnpm test src/foo.test.ts)
- Lint + typecheck: pnpm lint && pnpm exec tsc --noEmit

## Conventions
- Exact rules with examples ("use unknown + type guards, never any")
- Folder structure notes that aren't obvious from names

## Workflow
1. Read relevant code before editing
2. Plan non-trivial work in a scratch file
3. Tests + lint must pass before done

## Forbidden
- Things that look reasonable but are wrong here
  ("don't add dependencies without asking", "never edit generated/ files")

The rules that make it work

1. Exact commands, copy-paste ready. "Run the tests" is useless; pnpm test src/foo.test.ts is gold. Commands are the most-used part of the file.
2. Keep it short. Every line spends context-window budget on every task. Under ~150 lines is ideal; link out to deeper docs instead of inlining them.
3. Forbidden > preferred. Agents follow "never do X" far more reliably than vague style preferences. List the mistakes that actually happened.
4. Maintain it like code. When an agent does something wrong twice, that's a missing line in AGENTS.md. Update it in the same PR.
5. Show, don't describe. One short code snippet of the house style beats three sentences explaining it.

Monorepos: nested files

Place additional AGENTS.md files in subprojects. Runners use the nearest file to the code being edited, so the root file holds shared rules and each package adds its specifics:

repo/
├── AGENTS.md            ← shared conventions, top-level commands
├── apps/web/AGENTS.md   ← frontend-specific rules
└── packages/api/AGENTS.md

Common mistakes

• The novel — 600 lines nobody (human or agent) maintains. Trim ruthlessly.
• The duplicate README — agents can read your README; don't paste it again.
• Stale commands — a wrong test command is worse than none. Verify after tooling changes.
• Aspirational rules — "write beautiful code" does nothing. "Functions over 40 lines need a refactor reason in the PR" does.

See a complete, production-grade example: AGENTS.md for Next.js + TypeScript.