[!todo] Seed note. A starting point, not a finished note yet.
AGENTS.md (and tool-specific kin like CLAUDE.md) is a checked-in markdown file that steers agents touching a repo: exact build/test commands, project structure, code style by example, git workflow, and boundaries expressed as tiers (always / ask-first / never). It differs from an Architecture Decision Records entry by being prescriptive rather than historical: an ADR records what was decided and why, an AGENTS.md enforces what must always and never happen when changing the code. A GitHub analysis of 2,500+ such files found most fail by being too vague, which matters because models fill gaps with plausible-but-wrong defaults. Seeded from Upfront Planning in the AI Era - PRDs, Design Docs, and Specs; an instance of Context Engineering.