What a decision record is
An Architecture Decision Record (ADR) is a short note capturing a significant decision: the context that forced it, the choice made, and the consequences. It's the institutional memory of 'why is it like this?'.
ADRs have been good practice for years; AI assistance makes them more valuable, not less.
Why AI teams need them more
AI agents are stateless and have a finite context window, so any decision whose rationale isn't written down gets rediscovered — and often re-debated — every session. The agent 'helpfully' proposes the option you already rejected.
A written record gives the agent (and new teammates) the reasoning, so settled questions stay settled.
The minimal format
Keep it to three parts: Context (what situation/constraints), Decision (what we chose), Consequences (trade-offs and what it rules out). A few sentences each is plenty.
Brevity is the point — an ADR nobody writes because it's heavyweight provides zero memory.
Where to keep them
Store ADRs in the repo (e.g. a docs/decisions folder) and reference them from your project memory file so agents read the relevant ones in context.
Decisions that live only in someone's head — or a buried chat thread — are invisible to both teammates and agents.
Make it a habit
Capture the record at the moment of decision, while the reasoning is fresh. Recovering it weeks later is exactly the expensive work ADRs exist to prevent.
A lightweight, consistent habit beats an elaborate process used once.