Capture the reasoning behind a decision, so the team and its agents stop re-litigating it.
The team friction Decisions made in a meeting evaporate. Three weeks later nobody remembers why the team chose this queue over that one, so it gets re-argued, or worse, quietly reversed by whoever touches it next — often an agent that has no idea a decision was ever made. The team keeps paying for the same choice repeatedly.
The pattern The team writes Architecture Decision Records: short, dated notes capturing the decision, the context, and the rationale and alternatives considered. Not what the code is — why it’s that way. They live in the repo, are written when the decision is made, and are the first answer to “why is this like this?”
Why it works with AI Rationale is exactly what code can’t show and what agents most need: an agent reading the code sees what, never why, so it will happily “improve” a deliberate choice. An ADR is durable context that steers future agents and onboards humans in one read.
Watch-outs ADRs record decisions and their reasons — keep them distinct from agent-written docs (which describe the system) and product memory (durable knowledge agents read from). One decision, one short record; don’t bloat them into design essays nobody updates.
Related Product memory · Agent-written shared docs · Consistent, excellent codebase