do-agents-md

Structure AGENTS.md as a short table of contents with sections for commands, repository structure, architecture boundaries, coding standards, testing, commit conventions, and guardrails. Keep it under roughly 150 lines and point to deeper docs rather than duplicating them.

Include concrete build, test, lint, and format commands, a one-line-per-directory repository map, architecture dependency rules, only non-obvious project-specific coding standards, testing patterns, commit conventions, and explicit never-do boundaries.

Keep AGENTS.md around 100-150 lines. Longer files crowd out the actual task context, cause agents to pattern-match locally instead of navigating, and become stale quickly. Point to deeper documentation for details.

Place a root AGENTS.md for global rules like commit conventions and shared tooling, then add nested AGENTS.md files per package for package-specific instructions. The file closest to the edited code wins, and nested files should only cover what differs from the root.

Avoid writing 500+ line prose documents, listing rules the linter already enforces, vague instructions like write clean code, stale conventions, and omitting the commands needed to build and test. Stale rules are worse than no rules because agents follow them faithfully.