How to write AGENTS.md

Symptoms

• The agent rediscovers how to run tests every time
• Different agents produce code in different styles

Common causes

• The repository has no stable instructions for agents, or they are scattered across tool-specific files

How to fix

1. Create AGENTS.md at the repository root with the exact commands to install dependencies, build, run tests and lint
2. Add code-style rules, key points about the directory layout and things not to do (e.g. do not edit generated files, do not push to main)
3. In large repositories, add AGENTS.md files in subdirectories to override rules locally
4. Keep it short and concrete: commands and rules, not slogans; update it together with the code
5. Claude Code reads CLAUDE.md; reference or link AGENTS.md from it so you maintain one copy