winstonkoh87 📋 Spec-Driven Development
Philosophy: 55 minutes defining the problem, 5 minutes solving it.
1. The Problem
Most AI coding failures happen because the agent starts coding before understanding:
- What the user actually wants (vs. what they said)
- Edge cases and constraints
- Integration points and dependencies
- Success criteria
2. Execution Workflow
PHASE 1: INTERROGATION (No Code Allowed)
├─ "What is the ONE thing this must do?"
├─ "What does success look like? Be specific."
├─ "What are 3 things this must NOT do?"
├─ "Who/what does this interact with?"
└─ "What's the simplest version that would be useful?"
PHASE 2: SPEC DOCUMENT
└─ Write a design.md with:
├─ Goal (1 sentence)
├─ Requirements (numbered list)
├─ Non-Requirements (explicit exclusions)
├─ Architecture (how components connect)
├─ Edge Cases (what could go wrong)
└─ Acceptance Criteria (how to verify)
PHASE 3: USER APPROVAL
└─ Present spec for review
└─ DO NOT proceed to code until approved
PHASE 4: IMPLEMENTATION
└─ Code against the approved spec
└─ Reference spec line items in commits
3. The Spec Template
# Design Spec: [Feature Name]
## Goal
[One sentence describing what this does]
## Requirements
1. [Must do X]
2. [Must handle Y]
3. [Must integrate with Z]
## Non-Requirements (Out of Scope)
- [Will NOT do A]
- [Will NOT support B]
## Architecture
[How the components connect — diagram or description]
## Edge Cases
- [What if input is empty?]
- [What if API is down?]
- [What if user does X instead of Y?]
## Acceptance Criteria
- [ ] [Testable condition 1]
- [ ] [Testable condition 2]
4. When to Use
- Any feature that touches >3 files
- Any task that takes >30 minutes
- Any time you catch yourself thinking "I'll figure it out as I go"