spec-driven-dev

Skill: Spec-Driven Development

When working inside a repository that uses the spec-starter layout, follow this pattern at the start of every session.

Repository Layout

project-root/
├── spec/           # Development specifications
├── context/        # User preferences and domain context
├── decisions/      # Architectural decision records
├── iterations/     # Spec version snapshots
├── archive/        # Processed prompt files
└── CLAUDE.md       # Project summary and instructions

Reading the Spec

1. Look in spec/ for the latest specification:
   • If only spec/starter.md exists, use that
   • If versioned files exist (v2.md, v3.md, …), use the highest-numbered version
   • If unsure, ask the user which version is current

Reading Context

Read all files in context/:

• context/index.md is the primary context file
• Additional files (e.g., context/technology-stack.md) may be present — read them all

Context informs your choices about tools, languages, style, and constraints. It is supplementary; do not surface it unless it is directly relevant to the current task.

Speech-to-Text Awareness

The user's original prompt was likely captured via speech-to-text. When the user provides new input by voice, be alert for:

• Homophones (their/there, to/too, its/it's)
• Misheard technical terms ("Postgres" → "post grace", "OAuth" → "oh auth")
• Missing or incorrect punctuation

Infer the likely intended meaning when obvious; ask for clarification when ambiguous.

Spec Versioning

• Minor clarifications: edit the current spec in place
• Major direction changes: create a new versioned file (spec/v2.md, spec/v3.md, …)
• Claude Code automatically prefers the highest version number

Decision Tracking

When a significant architectural or technical decision is made, create a record in decisions/ using a date-prefixed filename: YYYY-MM-DD-description.md.

Iteration Snapshots

Before large refactors, snapshot the current spec by copying it to iterations/ with a descriptive name and timestamp, so the project's evolution is traceable.