AI coding agent guide
Write instruction files the agent can actually follow.
A useful CLAUDE.md or AGENTS.md is a compact operating contract: exact commands, repository map, scope rules, protected surfaces, verification, and stop conditions.
What belongs in the file
- Project map: the few paths and boundaries that matter.
- Exact commands: install, build, typecheck, test, lint, and smoke.
- Change rules: nearby patterns, scope discipline, and protected paths.
- Verification: what must be run for the changed surface.
- Stop conditions: ambiguity or risky changes that require human approval.
- Final report contract: files changed, commands, results, skipped checks, residual risk.
What to leave out
Generic advice the model already knows, long architecture prose it can read elsewhere, and vague rules such as “write clean code” or “test appropriately.” High-signal instructions should be observable by a reviewer.
A practical pattern
# Commands
- Test: npm test
- E2E: npx playwright test
# Scope
- Do not edit migrations or auth unless the task names them.
- Keep unrelated refactors out of the diff.
# Done
- Run relevant checks.
- Report exact commands and results.
- Disclose skipped checks and uncertainty.Go deeper
The AI Agent Repo Guardrails Pack adds reusable AGENTS.md and CLAUDE.md templates, protected-path rules, scope discipline, and done criteria. The AI Agent Operating Pack adds task handoffs and a review gate too.