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