Writing AGENTS.md

Write the smallest repository guidance that gives an agent the context, constraints, authority, and evidence needed to finish work safely.

Workflow

1. Resolve the target directory and all applicable AGENTS.md files. Explicit user instructions outrank repository guidance; the closest scoped file outranks ancestors. Default to one root file and add nested files only for genuinely different subproject rules.
2. Inspect current guidance, README/CONTRIBUTING, manifests, task files, CI, and relevant package docs. Verify paths and commands from executable configuration where possible; label unresolved facts instead of importing ecosystem conventions.
3. Identify generated, vendored, migration-sensitive, destructive, external, large-data, and ownership boundaries that materially change agent behavior.
4. Preserve correct project-specific rules and remove stale, repeated, speculative, generic, or misplaced content. Keep global rules in parents and local differences in children.
5. Verify every command and path, check the instruction chain for conflicts, run proportionate documentation or repository checks, and inspect the diff for duplication and scope growth.
6. For edits, report changed paths, purpose, checks, and caveats. For review, lead with concrete findings and replacement guidance.

Instruction Design