ADR and OpenSpec: Decision and Spec Management

TL;DR: ADR (Architecture Decision Records) documents the “why” behind architectural decisions, while OpenSpec 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 OpenSpec.

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 OpenSpec 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 2011¹, 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 guide²:

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.

OpenSpec

OpenSpec is a framework that embraces the spec-driven development (SDD) approach when working with AI coding assistants³. Its core philosophy is to clarify “what will be done” before implementation and ensure both human and AI stakeholders are on the same page.

OpenSpec’s lifecycle consists of three phases:

1. Propose: Human and AI coding assistant agree on the spec
2. Implement: Code is written according to the approved spec
3. Archive: Changes are incorporated into living documentation

Why OpenSpec?

AI coding assistants (Claude, Cursor, Gemini, GitHub Copilot, etc.) are powerful tools, but they can produce unexpected results without clear instructions. OpenSpec eliminates this ambiguity by:

• Locking requirements before implementation
• Providing deterministic and reviewable outputs
• Maintaining “what the code should do” as living documentation

ADR vs OpenSpec: Key Differences

Aspect	ADR	OpenSpec
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	Proposal → 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. A typical scenario works like this:

flowchart TD
    A[1. New feature incoming] --> B[Create OpenSpec proposal - WHAT]
    A --> C[Write ADR - WHY]

    B --> D[openspec/changes/add-2fa/]
    D --> E[proposal.md<br/>What will change]
    D --> F[tasks.md<br/>Implementation checklist]
    D --> G[specs/<br/>Requirements + scenarios]

    C --> H[docs/decisions/005-2fa-totp-vs-sms.md<br/>Why TOTP was chosen, why SMS was rejected]

OpenSpec defines “what” the feature is, while ADR documents “why” critical technical decisions within that feature were made.

Interview Phase (2025+)

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 OpenSpec’s “Propose” stage:

flowchart TD
    A[1. New feature incoming] --> B[Interview]
    A --> C[OpenSpec proposal - WHAT]
    A --> D[ADR - WHY<br/>if critical decision]

    B --> E[AI assistant asks clarifying questions]
    E --> F["Should this API fail-fast or retry?"]
    E --> G["Does it require auth?"]
    E --> H[Answers are incorporated into spec]

    C --> I[Enriched with interview outputs]

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

When to Use Which?

Situation	Approach
Adding feature/capability	OpenSpec
Breaking API change	OpenSpec
Choosing library X vs Y	ADR
Architectural pattern decision	ADR
Bug fix	Just commit message

Workflow with Worktree

Combining OpenSpec’s phases with git worktree enables parallel work:

Phase	Worktree?	Reason
Proposal	No	Just markdown, can be rejected
Implementation	Yes	Code changes, isolation matters
Archive	No	Post-merge, just file moving

# 1. Proposal (on main)
openspec/changes/add-feature/
├── proposal.md   # Ready for review
├── tasks.md
└── specs/

# 2. Worktree after approval
git worktree add ../project-add-feature -b feat/add-feature
cd ../project-add-feature

# 3. Implement (in worktree)
# ... write code ...

# 4. PR & Merge

# 5. Archive (on main)
openspec archive add-feature --yes

This approach prevents conflicts on main branch during large features.

Practical Implementation

To add these systems to your project, two files are sufficient:

1. docs/decisions/_TEMPLATE.md - ADR template
2. CLAUDE.md or reference in project configuration

An ADR template can have this structure:

# ADR-XXX: Title

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-YYY

## Date
YYYY-MM-DD

## Context
Describe the problem and current situation.

## Decision
What did we decide to do and why?

## Consequences

### Positive
- Benefit 1

### Negative
- Trade-off 1

## Alternatives Considered
- Alternative A: Why it was rejected

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. OpenSpec provides clarity before implementation, while ADR carries the reasoning behind decisions forward to future processes.

Together: complete context (what + why + how).

Further Reading

1. Architectural Decision Records
2. OpenSpec - Spec-Driven Development
3. AWS: Master ADRs Best Practices
4. Google Cloud: Architecture Decision Records Overview
5. Decision-Driven vs Spec-Driven Software Engineering
6. Claude Code: Best Practices for Agentic Coding
7. Gemini CLI Conductor: Context-Driven Development

Footnotes

1. Michael Nygard, Documenting Architecture Decisions, 2011 ↩
2. AWS Prescriptive Guidance, ADR Process ↩
3. Fission AI, OpenSpec: Spec-driven development for AI coding assistants ↩