Skip to content

Article Review: Group 17 — ADR Practice

Articles Reviewed

  1. "Why Does Our Code Work This Way? — Nobody Knows. ADRs Fix That." — Alina Kovtun / CodeToDeploy, Medium (Mar 2026) — Practical guide to Architecture Decision Records: when to write them, what sections to include, common mistakes, and how to introduce them to a team.

Key Concepts

The Problem: Whack-a-Mole Decisions

Teams waste time relitigating resolved architectural choices because nobody documented the reasoning. A new developer challenges a decision, the team reinvestigates, rediscovers the original reasoning was sound — but nobody documented why, so everyone relitigates what. The mole keeps popping up.

Mental test for whether an ADR is needed: "If the two people who made this decision left tomorrow, would the rest of the team know why we did this?"

When to Write an ADR

Reserve for decisions that meet one or more of: - Affects how developers write or structure code - Hard or expensive to reverse - Keeps getting revisited in meetings - New team members repeatedly ask about it - Affects multiple services, teams, or systems - Complex or difficult to explain without context - Overriding or adopting a decision made by another team

The 7-Section Template

  1. Title + Identifier — Name the decision, not the topic. ADR-012 Use PostgreSQL for the Media Service beats ADR-012 Database Selection.
  2. Status — Keep it simple: Draft → Decided → Superseded by ADR-XXX. Three statuses cover almost every situation.
  3. Context — Why the decision needs to be made. Include assumptions and flag them explicitly.
  4. Evaluation Criteria — What architecture characteristics matter (performance, fault tolerance, extensibility, cost, compliance). This is what separates good ADRs from mediocre ones — without criteria, the decision looks arbitrary.
  5. Options Considered — No more than three. Score each against criteria in a table. Include cost calculations, benchmarks, POC results.
  6. Decision — One short paragraph connecting context, criteria, and options. A decision statement, not a vague conclusion.
  7. Implications — Both positives and negatives. Documenting downsides warns future maintainers what to watch for.

Five Common Mistakes

  1. Writing ADRs after the fact — Write during the decision process, not as a post-decision report. Memory loses nuance fast.
  2. Skipping evaluation criteria — Without criteria, a decision is a preference. With criteria, it's an argument.
  3. Storing per project instead of per product — Projects end, products continue. Store ADRs against the product.
  4. Too many statuses — Three statuses (Draft, Decided, Superseded) cover nearly everything. Complex workflows add overhead without value.
  5. Not referencing ADRs from code — Add // See ADR-012 comments in the codebase so developers encounter the reasoning at the point of use.

Adoption Strategy

Don't mandate — demonstrate. Start by writing ADRs for decisions already made (the ones new engineers ask about most). Share ADR links in Slack instead of re-explaining. Integrate into existing processes: add "does this decision need an ADR?" to sprint planning, make ADR review part of onboarding, add an ADR link field to PR templates.

The Deeper Value

ADRs force structured reasoning, which produces better decisions — not just better documentation. They also build psychological safety: a developer who finds an ADR blocking their proposed change feels informed, not dismissed. And they make invisible knowledge (from meetings, Slack threads, 1:1s) survive team changes.

Relevance to Nextpoint

High relevance. We already have an adr/ directory with 11 ADRs and a /new-adr slash command. This article validated our approach and identified two gaps in our template:

Changes Made

  1. Updated adr/template.md — Added Evaluation Criteria section, Options Considered with scoring table, and optional Consultation section. Added guidance text explaining the purpose of each section.

  2. Updated .claude/commands/new-adr.md — Added Evaluation Criteria and Options Considered to the template. Updated prompts to ask for options during ADR creation. Added reminders to update superseded ADRs and suggest code comments referencing the ADR.

Comparison with Our Existing ADRs

  • ADR-001 through ADR-003: Minimal format — Context, Decision, Consequences. Would benefit from Evaluation Criteria and Options sections retroactively, but the decisions are well-established.
  • ADR-011: Already the most comprehensive, includes problem analysis, data flow diagrams, performance comparisons, and phased migration. Close to the article's ideal but would benefit from a formal Evaluation Criteria section.
  • Going forward: New ADRs should use the updated template with explicit criteria and scored options.

Tags

adr documentation architecture-decisions team-practices knowledge-management

Ask the Architecture ×

Ask questions about Nextpoint architecture, patterns, rules, or any module. Powered by Claude Opus 4.6.