Using AGENTS.md to Steer Claude Code in Your Repo

An AGENTS.md file (or similar rules doc) tells Claude Code how your repository expects to be modified: style, forbidden paths, test commands, and review etiquette. Good rules reduce bad diffs more than clever one-off prompts.

What to include

• Project overview in 5 — 0 lines.
• Package manager and test commands (npm test, pytest, etc.).
• Directories that are off-limits (/infra/prod, generated code).
• Formatting and naming conventions.
• Branch and commit message format.

Keep rules actionable

Vague "write clean code" lines waste tokens. Prefer "Run npm run lint before finishing" or "Do not edit package-lock.json manually."

Team workflow

Store AGENTS.md at the repo root. Reference it in onboarding. Update when architecture shifts — stale rules confuse agents.

Examples

## Testing
Always run `npm test -- --watch=false` after UI changes.

## Scope
Do not modify files under /legacy unless the ticket explicitly says so.

Measure impact

Track review comments before and after adding rules. Fewer style nits and smaller diffs mean the file is working.

Install the agent from our download page, add AGENTS.md, then retry the same ticket — compare diffs.