ADR (Architecture Decision Records) documents the “why” behind architectural decisions, while spec-driven development defines “what will be done” before implementation. When used together in AI-assisted development, they provide complete context: what + why + how to verify.
Continuing the series that includes principles like KISS and SoC, I want to cover two concepts gaining importance in AI-assisted development: Architecture Decision Records (ADR) and spec-driven development (SDD).
While these two approaches may seem similar at first glance, they fundamentally answer different questions. ADR focuses on “why did we choose this path?”, while SDD addresses “what will we do and how will we verify it?”
So, what are these two concepts and how can we use them together?
Architecture Decision Records (ADR)
ADR are structured documents that record architectural decisions made in a software project and the rationale behind them. This approach, popularized by Michael Nygard in 20111, makes it easier to answer “why did we make this decision?” especially in long-lived projects.
An ADR typically consists of these components:
- Status: Proposed, Accepted, Deprecated, Superseded
- Context: Describes the problem and current situation
- Decision: States what was decided and why
- Consequences: Lists positive and negative outcomes of the decision
Why ADR?
Software projects grow over time and team members change. Remembering why a decision was made six months ago becomes difficult. Questions like “Why did we use Zustand instead of Redux?”, “Why did we choose microservices over monolith?” remain unanswered without ADR.
As stated in AWS’s 2025 guide2:
An architecture decision record (ADR) is one of the most important deliverables of a solutions architect. This record documents the architecture decisions that you make throughout the design process and provides context-specific rationale for each decision.
Spec-Driven Development (SDD)
Spec-driven development is an approach that clarifies “what will be done” before implementation when working with AI coding assistants. Its core philosophy is to ensure both human and AI stakeholders are on the same page.
One of the frameworks that popularized this approach in the AI ecosystem is OpenSpec3. OpenSpec formalized spec management with a propose-implement-archive lifecycle. However, the ecosystem evolved rapidly: today, AI coding assistants’ own brainstorming, planning, and evaluation capabilities serve the same function in a more integrated manner.
The approach hasn’t changed, the tools have.
Core Benefits of Spec-Driven Development
AI coding assistants (Claude, Cursor, Gemini, GitHub Copilot, etc.) are powerful tools, but they can produce unexpected results without clear instructions. The spec-driven approach eliminates this ambiguity by:
- Locking requirements before implementation
- Providing deterministic and reviewable outputs
- Maintaining “what the code should do” as living documentation
ADR vs SDD: Key Differences
| Aspect | ADR | Spec (SDD) |
|---|---|---|
| Focus | WHY (Why this approach?) | WHAT + HOW (What will be done, how will it be tested?) |
| Timing | Post-decision | Pre-implementation |
| Format | Lightweight (context, decision, consequences) | Formal (requirements, scenarios, specs) |
| Lifecycle | Write once, rarely update | Spec -> Evaluate -> Implement -> Archive |
| Scope | Architectural/technical decisions | Feature/capability changes |
| Target Audience | Architects, developers, stakeholders | Developers working with AI assistants |
Using Together
These two approaches are not alternatives but complements. Spec defines “what” the feature is, while ADR documents “why” critical technical decisions within that feature were made. For a 2FA implementation, the spec would cover which flows the feature supports and how it integrates with the session layer; the ADR (e.g., docs/decisions/005-2fa-totp-vs-sms.md) would document why TOTP was chosen over SMS.
Interview Phase
Modern AI coding assistants support an interview phase before implementation:
| Tool | Approach | Output |
|---|---|---|
| Claude Code | AskUserQuestion + Plan Mode | plan.md |
| Gemini CLI | Conductor + Onboarding Interview | product.md, tech_stack.md |
This phase strengthens the spec creation process. The AI assistant asks clarifying questions (“Should this API fail-fast or retry?”, “Does it require auth?”) and the answers are incorporated into the spec before any code is written.
Benefits:
- Assumptions surface early: At the start, not during code review
- Decision tree is navigated upfront: Each question is a fork, each answer narrows the solution space
- Spec becomes more deterministic: AI executes without ambiguity
From Foundations to Workflow
Tools evolved quickly. What was a single openspec proposal command in January 2026 is now a brainstorm -> court -> plan -> implement -> critique -> retro pipeline, with git worktree isolating implementation from main. That operational layer — how the multi-AI tribunal actually runs, what the worktree flow looks like, how ADRs get auto-generated — gets its own treatment in From OpenSpec to Brainstorm + Court: Spec-Driven Workflow with Worktree.
If you’ve internalized the ADR vs SDD distinction above, that post is the natural next step. It also covers a practical ADR template you can drop into your repo.
Relationship with Decision Gate
ADR and spec document the “why” and “what” of a decision. But there’s a question that comes before both: “should we?” For the framework that answers this question, see Decision Gate: The Missing Piece of Vibe Coding.
| Question | Tool | Timing |
|---|---|---|
| Should we? | Court / Decision Gate | Pre-decision |
| Why did we choose this path? | ADR (Court output) | Post-decision |
| What will we build, how will we verify? | Spec (Brainstorm) | Pre-implementation |
Conclusion
With the proliferation of AI-assisted development tools, providing systematic answers to “what will we do” and “why did we choose this path” becomes increasingly important. ADR and spec are not alternatives — they cover different questions, and used together they complete the context an AI agent or a future teammate needs.
For how these two layers turn into a running operational pipeline (brainstorm, court, plan, implement, critique, retro) and how git worktree fits in, continue with Spec-Driven Workflow with Worktree.
I examine how ADRs transform into executable constraints for AI agents, the Codified Context approach, and other architecture documentation alternatives in detail in Living Architecture Documentation for AI Agents. You can also check out the Living Architecture project where I converted these research findings into a project-agnostic template.
Further Reading
- Architectural Decision Records
- OpenSpec - Spec-Driven Development
- AWS: Master ADRs Best Practices
- Google Cloud: Architecture Decision Records Overview
- Decision-Driven vs Spec-Driven Software Engineering
Footnotes
- Michael Nygard, Documenting Architecture Decisions, 2011 ↩
- AWS Prescriptive Guidance, ADR Process ↩
- Fission AI, OpenSpec: Spec-driven development for AI coding assistants ↩
- 01 ADR documents the 'why' behind architectural decisions; the reasoning is preserved even months later
- 02 Spec-driven development defines 'what will be done' before implementation, providing full context to AI agents
- 03 When used together, the what + why + how to verify loop is complete
- 04 In AI-assisted development, generating code without a spec leads to context loss and incorrect output
- 05 The approach stays constant: spec first, then code — tools evolve, principle remains
+ What is ADR (Architecture Decision Records)?
ADR are structured documents that record architectural decisions made in a software project and the rationale behind them. Popularized by Michael Nygard in 2011.
+ What is spec-driven development and how does it differ from ADR?
Spec-driven development is an approach that clarifies requirements before implementation when working with AI coding assistants. While ADR focuses on 'why did we choose this path', spec addresses 'what will we do and how will we verify it'.
+ How are ADR and spec used together?
Spec defines what a feature is, while ADR documents why critical technical decisions within that feature were made. Together they complete the what + why + how to verify loop.
+ Why are specs necessary in AI-assisted development?
AI coding assistants can produce unexpected results without clear instructions. Spec locks requirements before implementation, providing deterministic and reviewable outputs.