A software decision that exists only in a chat may be invisible to the next person—or the next AI-assisted work session—that needs to follow it. An architecture decision record (ADR) gives important choices a durable, findable home, including the reason behind the choice and its consequences. It is a practical way to preserve project context, not a guarantee that future work will follow it.
Why a chat decision can disappear
Derek Wang makes this case in his DEV Community essay, “A decision you didn’t write down isn’t a decision”, published September 20, 2026. His concern is that a later session may begin without the conversation that settled an important technical choice. In AI-assisted work, that can mean a new session lacks the context that a teammate might also miss when joining a project.
As an Amazon Associate I earn from qualifying purchases.
Wang describes memory drift, architecture drift, and repeated arguments as patterns he has encountered. These are his practitioner observations, not measured rates or proof that chat causes a particular amount of rework. His concise warning, “A conversation is not a contract,” is rhetoric rather than standards language. The practical point is narrower: if a decision must guide future changes, put it somewhere those changes can find it.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →What an ADR records
An architecture decision record captures an important choice together with the context and consequences that make it understandable later. The Nygard decision record template offers a lightweight starting point with five fields:
#1 Best Overall
- Title: A short name that makes the choice easy to identify.
- Status: Whether the decision is proposed, accepted, rejected, deprecated, or superseded.
- Context: The situation or problem that prompted the decision.
- Decision: What the project chose to do.
- Consequences: What becomes easier, harder, or otherwise changes as a result.
The template credits Michael Nygard’s book Documenting Architecture Decisions as its source. The broader ADR community resources describe a project’s collection of records as its decision log and offer multiple template approaches. Nygard’s fields are a useful baseline, not a mandatory universal standard.
How to put the decision log to work
- Choose a home near the project. Store important records with the files and documentation that people—and tools—use when making later changes. A record hidden somewhere difficult to discover is less useful.
- Write the reason as well as the choice. State the context, the selected approach, its status, and the consequences. Preserve meaningful alternatives or trade-offs when they explain why this option made sense; a bare instruction may not help a future reader judge whether circumstances have changed.
- Make the lifecycle clear. If a decision changes, update the status and link or otherwise identify its relationship to the replacement. Two records that both look current can leave readers unsure which guidance to follow.
- Surface the record in the work that needs it. Link to relevant ADRs from project guidance, review steps, or the task workflow. Wang cautions that a record nobody reads or checks cannot, by itself, prevent drift. Writing it down preserves information; the team still has to bring that information into later decisions.
Choosing an ADR format
There is no single format established as best for every team. Compare templates by the work they ask of authors and the guidance they give future readers:
- Detail: Can the team fill it in for consequential choices without turning routine decisions into paperwork?
- Alternatives and trade-offs: Does it provide space to explain why other options were not selected?
- Status and replacement: Can readers tell whether a choice is accepted, no longer current, or superseded?
- Workflow fit: Can contributors find and maintain records in the team’s normal project workspace?
Wang gives examples from his own repositories—20 ADRs for TradeOMS and 11 for SmartQuant—and labels the counts “[ORIGINAL DATA].” They illustrate his practice only; they are not independently verified or an industry benchmark.
When to write one
Use an ADR when a choice is significant enough that future contributors need to know both what was selected and why. Architecture choices are the central use case, but the useful threshold is their effect on later work: if losing the rationale could lead to confusion, repeated debate, or a change made on incompatible assumptions, a concise record can help. Not every implementation detail needs one; the purpose is a usable decision log, not documentation for its own sake.
Quick Recap
Rank #3
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
