Prefer commands over descriptions
“Run quality checks” forces discovery. “Run pnpm lint and pnpm test” is executable. Add conditions when commands are expensive or only relevant to certain paths.
Define boundaries
Name generated files, vendored code, migration policy, ownership boundaries, and directories with separate instructions. Explain which nested file wins.
Use proportional verification
State the minimum focused check and when a full suite, build, integration test, snapshot update, or migration validation becomes necessary.
Keep reference material elsewhere
AGENTS.md enters the working context frequently. Link deep architecture or operational runbooks; retain only the instructions required to navigate and verify changes.
Audit unsafe examples
A code block is still guidance. Avoid normalizing force pushes, broad recursive deletion, sudo, disabled certificate checks, or --no-verify.