Stop Writing Code First. Start Writing Specs

How the SDD Workflow plugin for Claude Code turns vague ideas into shipping software — with traceability built in.

If you've ever shipped a feature that didn't match what was asked for, or merged code no one could explain weeks later, you know the problem: code without context is just text. Spec-Driven Development (SDD) flips the workflow: write what you’re building before you write how. The SDD Workflow plugin for Claude Code enforces this end-to-end — from domain model to deployment guide — so every change in code maps back to a decision and a requirement.

Why this matters

• Reduces rework and surprise behavior by forcing requirements up front.
• Improves onboarding: newcomers read DOMAIN, REQUIREMENTS, and SPEC artifacts instead of guessing intent from code.
• Creates auditability: each commit or PR links to a requirement and a design decision.
• Makes reviews faster: reviewers validate intent changes rather than hunting for hidden assumptions in diffs.

How the SDD pipeline works Every system design blueprint follows a phased SDD pipeline. Each phase has a make target, produces a concrete document, and gates the next phase (the review gate must pass to continue):

Notes:

• Traceability flows backward: SPEC.md references REQUIREMENTS.md; DESIGN.md references SPEC.md; BUILD_GUIDE.md references DESIGN.md. That preserves an auditable trail from runtime behavior back to domain intent.
• The review gate combines automated checks (validation, linters, semantic diffs) and manual sign-offs. If REVIEW.md items fail, the pipeline stops and blocks merges.

How the plugin enforces the workflow The SDD Workflow plugin for Claude Code automates the pipeline and prevents accidental shortcuts:

• Templates & scaffolding: generates DOMAIN.md, REQUIREMENTS.md, SPEC.md templates with required headings and metadata.
• Validation rules: ensures required sections exist and that every spec element references one or more requirement IDs.
• CI/PR gating: blocks merges if traceability is broken or required review checks aren’t satisfied.
• Stable IDs & metadata: auto-assigns IDs (REQ-0001, SPEC-0002) and includes lightweight changelogs to map commits to spec changes.
• Semantic diffs: highlights intent-level changes between SPEC versions so reviewers focus on behavior deltas, not formatting noise.
• Artifact diff checks: flags untracked changes to specs, designs, or build guides before CI runs the build.
• Diagram generation: converts structured sequence/flow definitions into diagrams embedded in DESIGN.md.
• Integrations: optional commit hooks, CI tasks, and issue/PR templating that embed requirement/spec links into PR descriptions.

Minimal worked example This tiny example shows the linking pattern the plugin enforces. The plugin verifies that SPEC entries implement at least one REQ ID.

# DOMAIN.md
Contexts:
- Payments

# REQUIREMENTS.md
- REQ-0001: Process a one-time card payment of up to $10,000.
- REQ-0002: Return a transaction ID and status within 2s for successful payments.

# SPEC.md
- SPEC-0001 (implements REQ-0001, REQ-0002):
  POST /payments
  Request:
    { "amount": number, "currency": "USD", "card": { ... } }
  Response:
    { "transaction_id": "tx_123", "status": "succeeded" }

When a developer updates SPEC.md, the plugin:

• Validates that SPEC-0001 lists REQ IDs.
• Generates a semantic diff of the previous SPEC-0001 and surfaces it in the PR.
• Marks the PR as blocked if REVIEW.md checklist items haven’t passed (for example: load-test, security review).

How to get started (practical steps)

1. Scaffold the artifacts:
   • make domain → generates DOMAIN.md scaffold.
   • make reqs → adds REQUIREMENTS.md template.
   • make spec → creates SPEC.md starter.
2. Fill minimum required fields (titles, IDs, short descriptions).
3. Run make review locally or in CI. Fix any validation errors flagged by the plugin.
4. Open a feature branch, update SPEC and code together, then open a PR. The plugin will:
   • Show semantic diffs.
   • Verify all SPEC entries reference REQ IDs.
   • Block merge until REVIEW.md checks pass.
5. When ready, make build documents final build & deployment steps.

Adoption checklist

• Start with a small feature: use the pipeline on one endpoint or service before rolling it org-wide.
• Define minimal required metadata (ID, title, short rationale) for each artifact to keep friction low.
• Configure CI gating gradually: begin by reporting validation errors, then enforce blocking merges.
• Train reviewers to focus on spec/requirement diffs, not purely code diffs.

Common concerns and tips

• “This adds overhead.” Treat SDD as an investment: early alignment prevents late rework and expensive rollbacks. Start small and tighten gates over time.
• “Specs go stale.” Use the plugin’s artifact diffing and CI hooks to flag stale specs. Make spec updates part of the PR that changes code.
• “Who owns the specs?” Domain authors or product managers draft requirements; engineers own the SPEC and DESIGN that implement them. Traceability forces a conversation, not a blame game.

Closing: where this gets you Shift the burden from guessing intent in code to documenting intent up front. The SDD pipeline and the SDD Workflow plugin for Claude Code don’t eliminate tradeoffs — they make them explicit, auditable, and reviewable. That reduces rework, speeds onboarding, and makes every commit answerable: “Which requirement does this change satisfy?”

Try it on one feature branch, keep artifacts minimal, and iterate on the gating policy. If you want, I can:

• Draft a tiny DOMAIN.md/REQUIREMENTS.md/SPEC.md for a concrete feature in your project.
• Produce a sample Makefile that wires the pipeline together.
• Suggest reviewer checklist items for REVIEW.md.

Which of those would you like next?

How the SDD Workflow plugin for Claude Code turns vague ideas into shipping software — with traceability built in.

If you've ever shipped a feature that didn't match what was asked for, or merged code no one could explain weeks later, you know the problem: code without context is just text. Spec-Driven Development (SDD) flips the workflow: write what you're building before you write how. The SDD Workflow plugin for Claude Code enforces this end-to-end — from domain model to deployment guide — so every change in code maps back to a decision and a requirement.

Why this matters

• Reduces rework and surprise behavior by forcing requirements up front.
• Improves onboarding: newcomers read artifacts (DOMAIN, REQUIREMENTS, SPEC) instead of guessing intent from code.
• Creates auditability: each commit or PR links to a requirement and a design decision.

The SDD pipeline Every system design blueprint follows a phased SDD pipeline. Each phase has a make target, produces a concrete document, and gates the next phase (the review gate must pass to continue):

Notes:

• Every artifact links backward: SPEC.md references REQUIREMENTS.md; DESIGN.md references SPEC.md; BUILD_GUIDE.md references DESIGN.md. This preserves traceability from runtime behavior back to domain intent.
• The make review step is an explicit gate: the checklist in REVIEW.md must pass (automated and manual checks) before the pipeline continues.

How the plugin enforces the workflow The SDD Workflow plugin for Claude Code automates and enforces the pipeline so teams don’t skip steps:

• Templates & scaffolding: generate DOMAIN.md, REQUIREMENTS.md, SPEC.md templates with required headings and metadata.
• Validation: checks for required sections, IDs, and traceability links (e.g., every SPEC element must reference one or more REQ IDs).