Teams often remember the decision but forget why it was made. Six months later, a new developer sees a strange configuration, a product owner asks for a reversal, and everyone has to reconstruct a conversation from chat messages and half-remembered meetings.
A technical decision record, often called an ADR, is a small document that preserves the reasoning behind an important choice. It is not a design specification and it is not a meeting transcript. Its job is to make the decision understandable when the original people are busy, unavailable or no longer on the project.
Summary
- Record the problem, constraints, alternatives, decision and consequences in one short document.
- Write the record when the choice is made, then link it from the code or project documentation.
- Keep the decision honest: include trade-offs, rejected options and a review trigger.
What a decision record is — and is not
An ADR answers a narrow question such as “Why do we use a queue here instead of a synchronous request?” or “Why is this site deployed from a static build?” It should describe the decision at the level another engineer needs in order to work safely around it.
It is not a replacement for an implementation plan. The plan explains tasks, owners and dates. It is also not a promise that the decision can never change. A good record can be superseded when the constraints change; the old record still explains the history.
The useful unit is one decision. If a document contains five unrelated choices, split it. Readers should be able to point to one paragraph and say, “This is the rule we are following for this problem.”
The five parts worth writing
1. Context
Start with the situation that forced a choice. Mention the user or system problem, the relevant constraints and the facts that are already known. Avoid a long project history.
For example, a small site may need a deployment process that a non-specialist can repeat. The constraints might be a single main branch, a limited hosting environment and a requirement that generated files are checked before release. Those details explain why a simple build-and-publish workflow may be preferable to a larger platform.
2. Options considered
List the realistic alternatives, not every idea that appeared in a brainstorming session. Include the option that was already in use if it is being replaced. A short table or bullets is enough:
- Keep the current process and add checks.
- Adopt a managed deployment service.
- Build a custom release pipeline.
The point is not to prove that the chosen option was perfect. It is to show that the team considered the costs and boundaries of the choice.
3. Decision
State the outcome directly. “We will use…” is usually clearer than “It was decided that…”. Name the scope too. A decision might apply only to public content, only to production deployments or only to a particular service.
If the decision is conditional, write the condition. “We will use a queue for jobs that may take longer than the request timeout; short validation remains synchronous” is more useful than “Use a queue for performance.”
4. Consequences
Describe both benefits and costs. A queue can protect a request from a slow job, but it introduces retries, monitoring and eventual consistency. A static site can reduce runtime complexity, but editors need a source-and-build workflow. These are not objections to hide; they are part of the operating instructions.
Mention security, maintenance and failure modes when they matter. Readers should know what new responsibility the decision creates.
5. Review trigger
Add the condition that would justify revisiting the choice. It could be a traffic threshold, a hosting migration, a change in data sensitivity or a new product requirement. Avoid inventing a precise date just to make the document look complete.
A step-by-step writing workflow
- Name the decision as a question. Keep it narrow enough that one person can explain the answer in a few minutes.
- Collect constraints before proposing a solution. Include requirements, limits, dependencies and non-negotiable risks.
- Write two or three viable alternatives. Explain the important difference between them rather than listing product names.
- Choose an option and state why. Tie the reasoning back to the constraints.
- Record consequences honestly. Include what becomes easier, what becomes harder and what must be monitored.
- Ask the people who will operate the result to review it. A developer may miss an editorial, support or security consequence.
- Give it a status and link it. Use labels such as proposed, accepted, superseded or rejected, and link to related code, tickets or runbooks.
A small example
Suppose a website currently stores an API token in a local configuration file that is copied manually during deployment. The decision record should not merely say “move secrets to environment variables.” It should explain that the token must not enter the repository, that local development needs a documented setup path, that the deployment platform provides protected variables, and that rotation must be tested.
The alternatives might include continuing the manual file copy, using environment variables, or adopting a dedicated secret manager. The decision could be environment variables for this small deployment, with a review trigger if the number of services or operators grows. The consequence is that a new contributor needs setup instructions, while the repository no longer depends on a sensitive file.
Mistakes to avoid
The first mistake is writing only the conclusion. Without context and rejected alternatives, a future reader cannot tell whether the decision was deliberate or accidental.
The second is turning the document into a diary. A record should preserve reasoning, not every comment from the meeting.
The third is pretending uncertainty does not exist. If a performance claim has not been measured, say that it is an expectation and define how it will be checked.
The fourth is hiding the document in a private chat. Keep the source near the project documentation or repository and make the link discoverable from the relevant code, runbook or README.
Why it matters
Decision records reduce repeated debates. They help new contributors understand boundaries, give reviewers a place to challenge assumptions and make handoffs less dependent on memory. They also make reversals safer because the team can see which assumptions have changed.
The benefit is not bureaucratic completeness. It is a smaller amount of guesswork during the next incident, refactor or onboarding session.
My Take
The best decision record is short enough to read before a code review. If it needs a long appendix, keep the decision clear at the top and move supporting evidence elsewhere. Write it for the person who will inherit the system, not for the meeting that produced it.
Conclusion
A technical decision record is a compact memory aid for a team. Capture the context, realistic alternatives, chosen direction, consequences and review trigger while the reasoning is still fresh. Then link it where the decision will be encountered. That small habit turns “Why is it like this?” from a recurring investigation into a documented answer.