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