In practice
Six months ago you chose not to build a mobile app. A new teammate asks about it. With a log, you point to one entry: the date, why, what you would need to see to change your mind. Without one, you rebuild the argument from memory.
Michael Nygard proposed the architecture decision record, or ADR, on November 15, 2011: a short document for one decision, with a title, context, decision, status and consequences. The ADR site defines a decision log as the collection of ADRs kept in a project.
It isn't meeting minutes, which record talk. It isn't a roadmap, which records plans. And it isn't a changelog, which records what shipped. A decision log records why you chose.
A decision log template
- Title: the decision in one line, in the words you'd say aloud.
- Date and owner: who made the call, and when.
- Context: what was true, and the evidence (requests in the customer's words, the accounts, the revenue).
- Decision: what you chose, and what you ruled out.
- Why: the reasons, in two or three lines.
- Revisit when: the one fact that would change your mind.
- Status: proposed, accepted or superseded, with a link to the entry that replaced it.
Keep entries short. Never delete a superseded one, so the history stays readable.
Common mistakes
- Logging only what you chose. What you ruled out and why is what stops the repeat.
- Writing long entries nobody finishes. A few lines done beats a template left empty.
- Keeping the log somewhere your agents never read.
Why it matters for product builders
Decisions that live in a chat thread get lost, and then they get made again. The cost is the argument you pay for twice, and the work done against a call nobody remembers.
It matters more with agents. A coding agent can't recall a decision made in another session. If the decision isn't written where it reads, it builds the thing you ruled out.
What changes in AI-first products
The log has a new reader. People read it to settle an argument. Agents read it before they start, so a written decision changes what gets built. A decision kept in the rules file your agents read, such as AGENTS.md, reaches them before they start.
What didn't change is the effort of writing it down, and judging what deserves an entry. In Annsa, decisions are saved as principles that every agent reads: decide once, every agent learns.
See how Annsa does it: Memory →