Specification-Driven Development (SDD)

SDD is a disciplined approach to software development that requires explicit specifications before any implementation begins.

Core Principles

1. No Code Without Spec

RULE: Never write implementation code without an approved specification.

• •Prevents scope creep
• •Forces upfront thinking
• •Creates audit trail
• •Enables accurate estimation

2. Code-Free Spec (NEW)

RULE: Specifications describe WHAT to build, never HOW to code it.

Specs MUST contain:

• •User Stories (INVEST principle: Independent, Negotiable, Valuable, Estimatable, Small, Testable)
• •Acceptance Criteria (Gherkin format: Given-When-Then)
• •Non-Functional Requirements (measurable targets: "< 200ms p95", not "fast")
• •Edge Cases and error scenarios
• •Out of Scope (explicit exclusions)
• •Success Metrics (verifiable completion criteria)

Specs MUST NOT contain:

• •Implementation code or code snippets
• •Pseudocode or algorithm details
• •Function signatures or class definitions
• •Specific tool/library versions (use "current stable" or omit)
• •Step-by-step implementation instructions

Code References:

• •Use file:line pointers to existing patterns: "Follow pattern at src/services/auth.ts:23"
• •Describe what to reference, not the code itself: "Use the error handling pattern in utils/errors.ts"
• •NEVER copy code into specification documents

Why this matters for AI agents:

• •Specifications are contracts defining WHAT, not tutorials on HOW
• •AI agents perform better with goal-oriented specs than prescriptive instructions
• •Code in specs creates confusion: is it the requirement or just an example?
• •Keeps specs technology-agnostic and reusable

3. Ambiguity Tolerance Zero

RULE: If requirements are vague, DO NOT GUESS. Ask questions.

• •Assumptions cause rework
• •Clarification is cheaper than bugs
• •Users know what they want (with help)

4. Specification as Contract

RULE: The spec is the source of truth for implementation.

The spec defines:

• •What to build (functional requirements)
• •How well to build it (non-functional requirements)
• •When it's done (acceptance criteria)
• •What NOT to build (out of scope)

Development Phases

Relationship to Plan→Review→Implement Commands

The 5-phase model above is the logical abstraction. The plan→review→implement commands expand this into an operational workflow:

Quick Reference

Spec File Location

docs/specs/
├── SPEC-TEMPLATE.md      # Template for new specs
└── feature-*.md          # Feature specifications

Agent Integration

Additional Resources

For detailed information:

• •Complete Spec Template: See references/spec-template.md
• •Workflow Examples: See examples/workflow-example.md
• •Project Template: See docs/specs/SPEC-TEMPLATE.md

Balancing Structure with Flexibility

SDD provides structure, but rigid adherence can hinder effective problem-solving.

Goal-Oriented Approach

From Claude Code Best Practices:

"Claude often performs better with high level instructions rather than step-by-step prescriptive guidance."

Apply to SDD:

• •Phases define WHAT to achieve, not exactly HOW
• •Adapt approach based on task complexity
• •Skip phases when genuinely unnecessary (e.g., typo fixes)

When to Apply Full SDD

Flexibility Clause

The SDD workflow is a framework, not a checklist.

If you identify that a situation warrants deviation:

1. •Confirm all L1 rules are still respected (no code without understanding, no skipping security)
2. •Explain why the standard approach doesn't fit
3. •Proceed with the adapted approach

L1 Rules (Never Skip):

• •Understanding requirements before implementation
• •Security review for security-sensitive code
• •Approval for scope changes

L2/L3 (Adapt as Needed):

• •Number of exploration agents
• •Spec document format
• •Phase ordering for simple tasks

Rules (L1 - Hard)

• •NEVER implement without understanding requirements
• •ALWAYS clarify before assuming
• •NEVER add scope without approval
• •ALWAYS document significant deviations
• •NEVER include code snippets, pseudocode, or implementation details in specifications
• •ALWAYS use file:line references instead of copying code into specs

Defaults (L2 - Soft)

• •Create formal spec for features > 1 day effort
• •Use /spec-plan for new features (can use /quick-impl for obvious small tasks)
• •Acceptance criteria should be testable

Guidelines (L3)

• •Consider TDD for complex logic
• •Prefer parallel agent execution when independent
• •Document architectural decisions in ADRs