The Archaeology Problem
Six months into a project, someone asks: "Why did we use PostgreSQL instead of MongoDB?" or "Why does this service talk to the cache directly instead of through the gateway?" Without decision records, the answer is always the same: "I think someone decided that, but I don't remember why." The reasoning is lost. The context evaporated.
And now you're at risk of undoing a decision that had perfectly good reasons you can no longer recall. You might spend a week evaluating MongoDB — again — only to arrive at the same conclusion your past self already reached. That's the archaeology problem: you're excavating your own reasoning instead of building on it.
The fix isn't better memory. It's making architectural reasoning permanent.
The Approach: Records Capture Reasoning, Not Just Outcomes
Here's the mental model that changed how I think about decisions: the most valuable thing to preserve isn't *what* you chose — it's *why you rejected the alternatives*. Outcomes are obvious from the codebase. Reasoning isn't.
A decision record captures the full picture: the question being decided, the options you actually evaluated, the sources you consulted, the trade-offs you weighed, and the constraints that shaped the outcome. It's a snapshot of your thinking at a specific moment in time. And crucially, it's written knowing that future-you won't have that context.
The format doesn't need to be elaborate. What matters is that it's consistent, searchable, and complete enough to reconstruct the reasoning without having been in the room.
The Solution: Immutable Records That Build on Each Other
Every decision gets its own record. Once written, it's never edited — if circumstances change or a better answer emerges, you write a new record that references and supersedes the old one. This sounds rigid, but it's actually liberating. You never wonder whether a record reflects the original thinking or has been quietly revised. The history is complete.
Each record follows the same structure: the question, the domain (code, design, process, infrastructure), the research with source citations, the recommendation and rationale, the alternatives that were rejected, and the honest caveats about what you're still uncertain about. That last field matters more than it seems — acknowledging uncertainty now prevents overconfidence later.
After 175 decisions, the compound effect is significant. When a new question comes up, the first step is always: "Have we already decided this?" Often, we have. Decisions on persistence strategy are referenced by later decisions on service architecture. Decisions on service architecture shape decisions on testing. Each new decision is cheaper to make because it builds on established, documented foundations.
What We Learned
The biggest surprise was how useful decision records are as AI context. When an agent starts a task, it loads relevant past decisions. The agent knows what patterns we've chosen and why, what alternatives we've already rejected, and what constraints apply and where they came from. This prevents the most common failure mode of AI-augmented development: the agent makes a reasonable choice that directly contradicts an established architectural direction — not because it's wrong in isolation, but because it doesn't know the history.
With decision records loaded as context, agents follow established direction instead of inventing their own. The records don't just help humans remember — they make the reasoning machine-readable.
The other thing we learned: you don't need a perfect process to start. Write the record after the decision if you have to. Capture the reasoning while it's still fresh. The compounding value comes from consistency over time, not from having a perfect format on day one. Start with ten decisions. By the time you have a hundred, you'll wonder how you ever built anything without them.