{"post":{"slug":"architecture-decision-records-2026","title":"Architecture Decision Records: Writing Down the Why","excerpt":"Code shows what was built, never why. An ADR captures the reasoning, the alternatives, and the constraints that made a decision sensible at the time.","category":"code","date":"July 5, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">S</span>omeone joins the team, reads the code, and asks why it uses an unusual approach for something with an obvious standard solution. Nobody knows. The people who decided have moved on, and the decision looks arbitrary — so it gets changed, and three months later the original constraint reappears as an incident.\n\nAn architecture decision record prevents that specific and very common waste.\n\n## What changed in 2026\n\n- **Onboarding value became the main argument.** With teams changing composition faster, the case for written rationale shifted from documentation hygiene to practical onboarding speed.\n- **Records became context for AI assistants.** Coding agents reading a repository benefit from stated rationale in the same way new engineers do, which gave ADRs a second audience.\n- **Lightweight formats won.** Short, structured records displaced heavyweight design documents, which were written less often and read less still.\n- **Supersession became better understood.** Treating records as immutable history rather than living documentation clarified how to handle changed decisions.\n\n## What a record contains\n\n| Section | Content |\n| --- | --- |\n| Title and date | What was decided and when |\n| Status | Proposed, accepted, superseded by which record |\n| Context | The situation, constraints, and forces at the time |\n| Decision | What was chosen, stated plainly |\n| Alternatives considered | What else was evaluated and why it was rejected |\n| Consequences | What this makes easier and harder |\n\nContext and alternatives carry the value. The decision itself is usually visible in the code — you can see which database was chosen. What you cannot see is that the team had a two-week deadline, existing operational expertise in one system, and a data volume projection that turned out to be wrong. That is what makes a decision comprehensible later, and it is what tells a future reader whether the reasoning still applies.\n\nThe consequences section is the honest one. Every architectural decision makes some things easier and others harder, and writing the harder part down at the time is far more credible than reconstructing it later.\n\n## Keeping them useful\n\n**Keep them short.** A page is enough. Long records do not get written, and when they do they do not get read.\n\n**Store them with the code.** In the repository, in version control, reviewable in a pull request alongside the change they describe. A wiki elsewhere becomes stale and undiscoverable.\n\n**Supersede rather than edit.** When a decision changes, write a new record referencing the old one and mark the old one superseded. Editing history destroys the thing that makes the record valuable — knowing what was true when.\n\n**Write them for consequential decisions.** Choosing a database, a communication pattern between services, an authentication approach, a deployment model. Not for every library choice. Mandating a record for everything produces perfunctory records and trains people to skip reading them.\n\n**Write them at the time.** Reconstructed rationale is rationalization. The value comes from capturing the actual reasoning while the constraints are live.\n\nThey pair well with the debt argument in [tech debt tracking](/blog/tech-debt-tracking-2026), since a record explaining why a shortcut was taken is exactly what makes the eventual cleanup case.\n\n## Common mistakes\n\n- **Editing accepted records.** Destroys the historical value.\n- **Long design documents instead.** Written rarely, read less.\n- **Storing them outside the repository.** Undiscoverable and stale.\n- **Requiring one for every decision.** Perfunctory records, ignored process.\n- **Omitting rejected alternatives.** The most useful section, most often skipped.\n- **Writing them retrospectively.** Produces justification rather than reasoning.\n\n## FAQ\n\n**When should a decision get a record?**\nWhen reversing it would be expensive, when the choice is non-obvious, or when someone will ask why later. Those overlap heavily.\n\n**Who writes them?**\nWhoever made the decision, usually as part of the pull request implementing it.\n\n**What if the decision was wrong?**\nLeave the record and add a superseding one explaining what changed. A record of a decision that turned out badly is more instructive than one that turned out well.\n\n**Do they replace design documents?**\nFor discrete decisions, largely. Larger design work may still warrant a longer document, with ADRs recording the specific choices within it.\n\n## Where to go next\n\nFor related modelling practice, read [the C4 model explained](/blog/c4-model-explained-2026) and [event storming guide](/blog/event-storming-guide-2026). For the debt these decisions sometimes create, [tech debt tracking](/blog/tech-debt-tracking-2026).","hue":260,"metaTitle":"Architecture Decision Records Guide for 2026","metaDescription":"How to write ADRs that stay useful — capturing context and rejected alternatives, superseding rather than editing, and which decisions warrant one.","keywords":["architecture decision records","adr template","documenting design decisions","technical decision log","superseded decisions","engineering documentation","design rationale capture","onboarding context","software architecture 2026"],"tldr":["**An ADR records a decision, its context, and the alternatives rejected** — short, dated, and immutable once accepted.","**The context is the valuable part** — constraints that applied then explain choices that look wrong now.","**Supersede rather than edit** — a decision record is history, not documentation to keep current.","**Write them for decisions that are expensive to reverse** — not for every technical choice.","**Skip:** ADRs as a process requirement on everything. Mandated volume produces records nobody writes carefully or reads."],"readTime":"3 min read","wordCount":726},"related":[{"slug":"c4-model-explained-2026","title":"The C4 Model: Architecture Diagrams at Four Zoom Levels","excerpt":"Most architecture diagrams mix abstraction levels and mean nothing. C4 fixes that by defining four levels with a clear audience for each.","category":"code","date":"July 8, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":265},{"slug":"how-to-run-a-design-review-2026","title":"How to Run a Design Review in 2026: A Practical Guide","excerpt":"A design review is cheapest before any code exists, and most expensive after. Here is how to structure one that catches real problems instead of producing a rubber stamp or an unproductive debate.","category":"guides","date":"July 14, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":305},{"slug":"domain-driven-design-basics-2026","title":"Domain-Driven Design Basics for 2026: A Practical Primer","excerpt":"A plain-language introduction to domain-driven design in 2026 — bounded contexts, ubiquitous language, and when the pattern earns its complexity.","category":"code","date":"July 1, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":200}],"sameCategory":[{"slug":"bazel-build-explained-2026","title":"Bazel Explained: What Hermetic Builds Actually Cost","excerpt":"Bazel delivers reproducible, precisely cached builds and demands that you describe everything. Here is what you get, what it costs, and who should say no.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":145},{"slug":"graphql-federation-2026","title":"GraphQL Federation: One Graph, Many Teams","excerpt":"Federation composes independently-owned subgraphs into a single API. Here is what it solves, the operational cost it adds, and when a simpler gateway is enough.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":300},{"slug":"hermetic-builds-explained-2026","title":"Hermetic Builds Explained: Same Inputs, Same Output","excerpt":"A hermetic build depends only on declared inputs. Here is what that property gives you, the common leaks that break it, and how to move toward it incrementally.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":130},{"slug":"monorepo-tooling-compared-2026","title":"Monorepo Tooling Compared: What You Actually Need","excerpt":"Monorepo tools solve task orchestration and caching, not repository layout. Here is what each tier provides and how to tell when you have outgrown the simple option.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":150}],"newer":{"slug":"api-versioning-strategies-2026","title":"API Versioning Strategies in 2026: Picking One That Lasts","excerpt":"Every public API eventually has to change in a way that breaks existing clients. Here is how the main versioning strategies compare and how to pick one before you need it.","category":"code","date":"July 5, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":240},"older":{"slug":"async-communication-at-work-2026","title":"Async Communication at Work: A 2026 Guide","excerpt":"How async communication at work actually functions in 2026, where it beats meetings, where it fails, and how to write messages people can act on alone.","category":"guides","date":"July 5, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":260}}