SDD Design Doc Template

Use the design doc after the change proposal is reviewable. The purpose is to decide how the behavior will be implemented without losing the constraints from the spec.

design.md

# Design Doc

Spec:
Owner:
Status: Draft | Review | Approved

## Context
- Link to the approved spec or change proposal.

## Architecture Decision
- Chosen approach:
- Why this approach:
- Alternatives rejected:

## Interfaces
- API:
- Events:
- Database:
- UI states:

## Constraints
- Compatibility:
- Security:
- Performance:
- Operational limits:

## Rollout Plan
- Phase 1:
- Phase 2:
- Stop signal:
- Rollback:

When to use this template

The spec affects APIs, databases, queues, permissions, or release sequencing.
The team needs to compare two implementation approaches before coding.
Generated code needs a narrower architecture boundary.
A reviewer needs to understand why an alternative was rejected.

What a filled version looks like

The template becomes useful after it carries a real decision, owner, and evidence. This is the level of specificity to aim for.

## Architecture Decision
- Chosen approach: keep refund creation synchronous, move provider confirmation to async worker.
- Why: support needs an immediate pending state, while provider timeout can resolve later.
- Rejected: retry provider call inside request path because it increases duplicate risk.

Review before implementation

The chosen approach points back to the approved spec.
Interfaces list concrete endpoints, events, tables, or UI states.
Rejected alternatives include the reason, not just the name.
Rollout and rollback are specific enough for release review.

Weak vs strong wording

Weak

Use a worker and add tests.

Strong

Keep the refund request path idempotent. Create one local refund row, enqueue provider confirmation, block support from creating another refund while status is pending_provider_confirmation, and stop rollout if duplicate attempts exceed 0.5%.

FAQ

Should every spec get a design doc?

No. Use it when implementation choices create real risk. A small UI copy change can skip this step.

What belongs here instead of the spec?

Keep product behavior in the spec. Put architecture choices, trade-offs, constraints, interfaces, and rollout order in the design doc.

How do AI agents use it?

Give the agent the spec plus this design doc and require changed files to map back to the approved interfaces and constraints.

Related resources

Editorial note

This template is written for spec-driven development workflows. The example is illustrative and should be adapted to your domain.

Author: Daniel Marsh
Editorial policy: How we review and update content

Tip: keep it under /docs/specs/ or /.specs/, then update it in the same pull request as implementation changes. Last updated: May 11, 2026.