Architectural decisions deserve a durable log so that future change proposals can leverage prior reasoning during design — not rediscover it. OpenSpec with the default spec-driven schema captures that reasoning in design.md while a change is in flight, but once the change is archived, only specs.md is carried forward into openspec/specs/. The design rationale stays behind in the archive, out of reach of future proposals. The new spec-driven-with-adr schema closes that gap by keeping Architectural Decision Records outside the change, alongside specs, so every architectural decision persists and the current state of the architecture stays visible to future proposals.

The Default spec-driven Schema

Default OpenSpec spec-driven schema producing proposal, specs, design, and tasks artifacts

OpenSpec ships with a default schema called spec-driven that produces four artifacts per change: proposal.md, specs.md, design.md, and tasks.md. When a change is archived, only specs.md is preserved — it is synced into openspec/specs/ and lives on. The proposal, design, and tasks are archived with the change under openspec/changes/archive/... and are not considered when the next change is proposed.

For more on how schemas plug into this pipeline, see the earlier post on OpenSpec Custom Schemas.

Why This Matters for Architectural Decisions

The rationale behind an architectural choice usually lives in design.md. Because design.md is archived with the change, that rationale becomes invisible to future proposals. New changes then get designed in the dark — the same trade-offs get re-litigated, fresh designs can quietly contradict prior ones, and the team loses the ability to see why the architecture looks the way it does.

How spec-driven-with-adr Differs

The spec-driven-with-adr schema adds an ADR artifact that lives outside the change, outside the openspec/ folder. Every change can write one or more ADRs (when there are significant architectural changes or decisions being made), and those records persist after the change is archived.

That gives the workflow two things the default schema does not:

  • A durable record of every architectural decision — context, options considered, choice, and consequences — captured at the moment the decision is made.
  • A visible current-state view of the architecture that future change proposals can read and design against.

The intent matches the rest of OpenSpec: keep the reasoning close to the code so future contributors — human or agent — can read the why without spelunking through pull requests, Slack, or memory.

Specs and ADRs Together Represent Current State

The earlier Source of Truth post framed openspec/specs/ as the living spec representing the current state of the system. The spec-driven-with-adr schema extends that same idea to architectural reasoning:

  • Specs represent the current state of the application’s overall functionality — what the system does today.
  • ADRs represent the current state of the application’s architecture — how and why the system is built that way today.

Both are durable, and both are read by future change proposals during design. Proposals, designs, and tasks are scaffolding that gets archived once a change ships; specs and ADRs are the load-bearing artifacts that future changes design against.

A Small Example

Suppose an early change picks Postgres over DynamoDB for the primary store. With the default schema, that decision is reasoned through in design.md — the alternatives considered, the cost and operational trade-offs, the consequences for query patterns — and then archived once the change ships. With spec-driven-with-adr, the same reasoning is captured as an ADR that persists outside the change.

A few months later, someone proposes “add full-text search”. During design, the agent (or human) reading sees the storage ADR, knows the system is on Postgres, and naturally evaluates pg_trgm and tsvector before reaching for a separate search service to infer the same from code. Without the ADR, that proposal can easily start by re-debating the storage choice, or worse, silently introduce a second store that contradicts the original decision.

Video Walkthrough

References