A Complete Guide to AGENTS.md
AGENTS.md is a Markdown file checked into Git that customizes how AI coding agents behave in a repo. Because the entire file is injected into context on every request, it consumes a finite instruction budget: frontier LLMs reliably follow roughly 150–200 instructions, while smaller models handle fewer. Oversized files also go stale quickly; outdated file paths and architecture notes actively poison agent context, unlike a human who can ignore bad docs. The guide argues for a minimal root AGENTS.md containing only a one-sentence project description, the package manager when it isn't npm, and any non-standard build/typecheck commands. Everything else should be progressively disclosed through linked markdown files, nested AGENTS.md files for monorepo packages, or agent skills. It also covers symlinking AGENTS.md to CLAUDE.md for Claude Code, and includes a copy-paste prompt to refactor an existing bloated file. Practical for teams running agentic coding tools who want to reduce token waste and document drift.