Architecture decision record
Also called ADR
A short text file in the repo recording one design decision: the situation, what was decided, and what it will cost. You don't rewrite it later. A new record replaces the old one.
An agent has no memory of why. Without a record it will see something odd and tidy it away, or reopen an argument that was already settled. Code shows what was chosen, and only a record says what was rejected.
Say it to your agent
“Write docs/adr/0007-one-deployable.md with Context, Decision, Status and Consequences, including what we rejected and why. Add a line to AGENTS.md: read docs/adr/ before changing how modules are split.”