What Is an Architectural Decision Record?
TL;DR: An architectural decision record (ADR) is a short markdown document that captures exactly why a technical choice was made. It outlines what was decided, the alternatives rejected, and the tradeoffs accepted. ADRs are stored alongside the code, which ensures that the reasoning behind the architecture outlives the coding session.
Why developers write ADRs
The code shows you what was built, while an ADR shows you why. Without it, architectural decisions disappear the moment they are made. Six months later, a new developer comes across a bizarre routing pattern or an outdated database wrapper. Without an ADR, they have no way of knowing if that choice was a deliberate workaround or an accidental hack. Changing it safely becomes pure guesswork.
Each record answers three questions:
- Context: What required this decision? Were there technical limitations, budget constraints, or strict timelines?
- Decision: What was the final choice, and which viable alternatives were rejected?
- Consequences: What does this choice make easier? What does it permanently break or block?
Teams usually store these as numbered markdown files in a /docs/decisions/ folder in the repo. A simple status tag (proposed, accepted, deprecated, superseded) tracks if the rule is still active.
Why ADRs matter more in AI-assisted development
When a human engineer makes an architectural decision, the reasoning often lives in their head and surfaces in Slack messages or code reviews. When an AI coding agent makes a decision, the reasoning disappears immediately. Agents do not carry context between sessions. They do not know what you decided yesterday, let alone why. If the agent doesn't have your architectural decisions explicitly in its context window, it will simply invent new ones. It will pick a schema that conflicts with your existing database or introduce dependencies that violate boundaries you established hours ago.
ADRs pre-empt this by making decisions explicit and machine-readable. Paired with a master architecture spec, they give the agent a reliable source of truth to anchor against before writing code.
Zalcro generates ADRs in a dedicated section within the ADD, which it produces at the start of every project.
Related terms
- What Is an Architecture Design Document (ADD)?
- What Is a Prompt Pack?
- What Is Spec-Driven Development?
- What Is Context Rot?
- What Is the 80% Wall?