The Decision Log: The Engineering Practice Your Future Self Will Thank You For
James Mitchell
Six months into building your product, a new engineer joins the team. Within their first week, they ask a question that stops you cold: “Why did we build auth this way? It seems like it’s making everything harder.”
You know the answer. You remember the three-hour debate, the security concerns, the third-party library that looked promising but had a deal-breaking limitation. You remember the tradeoffs weighed, the path not taken. But none of that is written down anywhere. It lives in your head, and in the heads of two other engineers who were in that room.
That new engineer stares at you. You stare back. You’re about to spend 45 minutes explaining something that should have taken 90 seconds to read.
This is the decision log problem. And it’s more expensive than most teams realize.
What a Decision Log Actually Is
A decision log — sometimes called an Architecture Decision Record (ADR) or simply a decision doc — is a short, structured document that captures why a significant technical or product choice was made. Not what was built. Why it was built that way.
The format is simple. Most teams use something like:
- Status: Proposed / Accepted / Deprecated / Superseded
- Context: What was the situation that forced this decision?
- Decision: What did we decide?
- Options considered: What else did we think about?
- Consequences: What does this make easier? What does it make harder?
That’s it. One page, maybe two. Written in the past tense once the decision is made. Stored next to the code it describes.
The format matters less than the habit. What you’re capturing is the reasoning — the shape of the problem as it existed when you made the call.
Why Teams Don’t Do This (And Why That’s a Mistake)
Ask any engineering team if they write decision logs and most will say “sometimes” or “we’re planning to start.” The honest answer is usually no.
The reasons are understandable. You’re moving fast. The decision feels obvious in the moment — who would ever forget why you chose Postgres over MongoDB? You’ll document it later. And besides, the code itself tells the story.
Except the code doesn’t tell the story. Code tells you what was decided. It says nothing about the five other things you considered, the constraint that ruled them out, or the assumption baked into the approach that might not hold in six months.
The cost of not documenting compounds. Every new engineer who joins has to reverse-engineer your architecture through conversations and archaeology. Every refactor risks undoing something that was deliberate. Every “why don’t we just…” debate gets re-litigated from scratch because the original context is gone.
Stripe’s engineering culture is famous for its documentation. Not because Stripe engineers have more time — they don’t. Because the people who built Stripe understood that institutional memory is a competitive advantage, and letting it walk out the door with departing engineers is a slow, quiet catastrophe.
The Three Moments That Demand a Decision Log
You don’t need to document every choice. That way lies paralysis and a docs folder no one touches. The goal is selective, high-value capture. Here are the moments that consistently justify the 15 minutes it takes to write one:
1. When you reject the obvious solution
The most valuable decisions to document aren’t the hard ones — they’re the ones where you chose the non-obvious path. When you looked at the standard approach and said “not for us, because…” — write that down. Future teammates will see the standard approach, not know your context, and propose it again. Save them the detour.
2. When you make a choice that will be hard to reverse
Some decisions are cheap to revisit. Others calcify into your system over time — database schemas, API contracts, auth patterns, monorepo vs. multi-repo structure. When a choice will be expensive to undo, document it. Not to prevent future teams from changing it, but so they understand exactly what they’re changing when they do.
3. When the decision depends on a constraint that might change
A lot of architectural decisions are really constraint-satisfaction problems in disguise. “We chose X because we had a team of three and couldn’t afford to maintain Y” is a completely valid and important thing to write down. When your team grows to twenty, a future engineer reading that log knows: the constraint changed, maybe the decision should too.
The Format That Actually Gets Used
The enemy of good decision logs is the blank page. Teams that start with elaborate templates end up with zero logs because no one ever feels like they have enough time to do it properly.
Keep it minimal. This is the template we’ve seen work best for small and mid-sized product teams:
## Decision: [Short title]
**Date:** YYYY-MM-DD
**Status:** Accepted
**Author:** [Name]
### Context
[2-4 sentences: what problem were we solving? what constraints existed?]
### Decision
[1-2 sentences: what did we decide?]
### Options Considered
- **Option A (chosen):** [Brief description + why chosen]
- **Option B:** [Brief description + why rejected]
- **Option C:** [Brief description + why rejected]
### Consequences
- Makes X easier
- Makes Y harder
- Assumes Z (revisit if this changes)
Write it in a Markdown file. Put it in a /decisions folder at the root of your repo, or in your docs folder. Name it sequentially: 0001-auth-strategy.md, 0002-database-choice.md. Commit it alongside the code it describes.
The sequential numbering is important. It gives you a timeline. You can look at your decision log from month 3 and see exactly what the team was wrestling with, in what order. That’s organizational memory.
Decision Logs and AI: The New Urgency
There’s a new reason decision logs matter that didn’t exist two years ago: AI coding tools.
Copilot, Cursor, Claude — these tools are remarkably good at writing code. They’re also remarkably good at suggesting code that contradicts your deliberate architectural choices. An AI assistant doesn’t know you decided to avoid ORMs because of your team’s performance requirements. It doesn’t know you chose a particular state management pattern because it integrates with your testing strategy.
Teams that have clear, well-documented decisions get more from AI tools. The documentation becomes context. You can drop a decision log into a prompt and get suggestions that respect your constraints instead of fighting them.
Some teams have started maintaining a CONTEXT.md or AI.md file at their repo root — a distillation of the most important architectural decisions, written for AI consumption. It’s a newer practice, but the underlying logic is the same as decision logs: make the implicit explicit.
As AI writes more of the code, the thinking that shapes the code becomes more valuable, not less. The engineer who can clearly articulate why a system is the way it is will always be more valuable than the engineer who can only describe what it is.
Getting Your Team to Actually Write Them
Documentation habits are culture problems, not tooling problems. Adding a JIRA ticket type for “decision log” won’t fix this. Here’s what does:
Make the first one for the team, not by the team
Don’t start with a workshop or a policy. Start by writing one. Find a recent significant decision, document it retroactively, and share it. “Hey, I wrote down why we chose our current deployment setup — figured it’d be useful context.” Let the artifact make the case for the practice.
Add it to your PR template
For significant PRs — new services, breaking API changes, architectural shifts — add a line to your PR template: “Does this decision need a log entry? (Link or N/A).” You’re not mandating documentation. You’re prompting the thought. Most of the time the answer will be N/A. Occasionally someone will stop and write a log instead of going with the default.
Reference them in reviews
When you’re reviewing code and you want to suggest an approach, link to a decision log if one exists. “We actually explored this option in decision-0003 — the constraint was X.” You’re teaching by example that these documents are living, useful references, not filing-cabinet artifacts.
Celebrate when they prevent work
When a decision log saves someone from a two-hour detour, say so out loud. “Good catch — we documented that in 0007, which is why we didn’t go down that path.” Make the value visible. Habits form when the feedback loop is clear.
What Happens When You Do This Consistently
Teams that maintain decision logs for a year or more report something that sounds almost philosophical: they get better at making decisions in the first place.
Writing down the context, the options, and the consequences forces a level of rigor that impromptu decisions often skip. When you know you’ll be documenting the alternatives you considered, you actually consider more alternatives. When you know you’ll be writing down the consequences, you think harder about the consequences.
The act of writing clarifies the thinking. That’s not a side effect — it’s one of the main benefits.
Onboarding gets dramatically faster. New engineers can read your decision logs and understand the shape of the system in a way that no README can convey. They see not just what you built, but the intellectual history of how you got there.
Debates get shorter. “Should we reconsider how we handle X?” starts with “let’s look at what we documented when we made that call” instead of “let me try to remember.” The shared artifact grounds the conversation.
And when something breaks — when a decision made under old constraints collides with new reality — you have a clean way to revisit it. You know exactly what assumption is no longer true. You know exactly what you’re changing.
Starting Tomorrow
You don’t need a new tool. You don’t need team buy-in. You don’t need to backfill every decision you’ve ever made.
Start with the next significant decision your team makes. Before you close the conversation, spend 15 minutes writing down what you decided, what you considered, and why. Drop it in a /decisions folder. Commit it. Share it.
That’s the whole practice. The rest is repetition.
The engineer joining six months from now will thank you. So will the version of you who’s staring at a system you built and trying to remember why you built it this way.
Write it down. Future you is counting on it.