spec-driven-development

Spec-Driven Development

A lightweight workflow for building production-quality Rails features with AI agents through systematic planning and self-contained specs.

Each spec is designed to be picked up and executed independently by Claude Code or a subagent — no extra context needed beyond the spec folder itself.

Each phase is driven by a /sdd-* slash command (see the Commands table at the end). The phase sections below are the reference each command follows — read them when running a phase, whether the user typed the command or asked in natural language.

Quick Start

New Rails Project (from MVP docs):

1. /sdd-init — creates sdd/ with pre-built Rails standards + index
2. /sdd-plan — convert MVP docs → product planning files
3. For each feature: /sdd-shape → /sdd-tasks → hand off to Claude Code

Adding Features to Existing App:

1. /sdd-init (if no sdd/ yet)
2. /sdd-discover-standards — capture patterns from the codebase
3. /sdd-shape → /sdd-tasks → hand off to Claude Code

---

Directory Structure

sdd/
├── product/
│   ├── mission.md            # Product vision, users, problems
│   ├── roadmap.md            # Feature priorities with effort estimates
│   └── tech-stack.md         # Technology decisions and deviations
├── standards/
│   ├── index.yml             # ← Catalog of all standards (auto-maintained)
│   ├── global/
│   │   └── rails-stack.md
│   ├── backend/
│   │   └── rails-patterns.md
│   ├── frontend/
│   │   ├── hotwire.md
│   │   └── components.md
│   └── testing/
│       └── minitest.md
└── specs/
    └── YYYY-MM-DD-feature-name/
        ├── spec.md           # Requirements, user stories, scope
        ├── references.md     # Existing code to reuse/follow
        ├── standards.md      # Standards that apply to THIS feature (injected from index)
        └── tasks.md          # Task groups with self-contained Claude Code prompts

---

Standards System

Standards are short .md files. Every word costs tokens — keep them concise and scannable.