spec-driven-development

## Overview Specification-driven development forces clarity before commitment. A spec written before code reveals ambiguities, surfaces missing requirements, and creates a shared contract between implementer and reviewer. Code written without a spec is often solving the wrong problem correctly. ## When to Use - Before implementing any new feature or significant change - When requirements are unclear or verbally communicated - Before writing any public API or interface - When multiple engineers will work on the same feature ## Process ### Step 1: Capture the raw requirement Write down what you've been asked to build, in plain English, without interpretation. Include the source (ticket, conversation, PR comment). ### Step 2: Identify stakeholders and success criteria Answer: Who uses this? How do they know it works? What does failure look like? ### Step 3: Write functional requirements List what the system must do. Use "The system shall..." or "When X, then Y." Each requirement must be independently testable. ### Step 4: Write non-functional requirements Document: performance expectations, security constraints, accessibility requirements, scale targets, error handling expectations. ### Step 5: Define the data model Sketch the inputs, outputs, and state transitions. Identify what data must be stored, what must not be stored, and what can be computed. ### Step 6: Define the interface contract For APIs: endpoints, methods, request/response shapes, error codes. For UIs: wireframe or component tree, states (loading, empty, error, populated). For libraries: public function signatures and contracts. ### Step 7: List open questions Document every assumption you made and every question you don't have an answer to. Get answers before writing code. ### Step 8: Get sign-off Have the spec reviewed by at least one stakeholder before starting implementation. A spec that nobody reads is not a spec. ## Anti-Rationalizations **"This feature is obvious — I don't need to write it down"** If it's obvious, the spec takes 10 minutes. If it's not obvious, the spec saves days. Either way: write it. **"We'll iterate quickly — the spec will be wrong anyway"** Iteration is not an excuse to skip specs. It means you write smaller, tighter specs for each iteration. Iterating on code without a spec means iterating in circles. **"The ticket has enough detail"** Tickets capture requests, not contracts. A spec translates requests into testable requirements. These are different things. ## Red Flags - Implementation started before all open questions are resolved - Spec has no acceptance criteria - "I'll just figure it out as I go" - Spec written after implementation to explain what was built ## Verification Requirements Before starting implementation: - [ ] Functional requirements listed and independently testable - [ ] Non-functional requirements documented - [ ] Interface contract defined - [ ] Open questions list is empty (all answered) - [ ] At least one stakeholder has reviewed the spec - [ ] Acceptance criteria are measurable, not subjective