Menu
Write a specification before writing any implementation code
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Build UIs that work for all users including keyboard navigation, screen readers, and WCAG 2.2
Design multi-agent systems with robust tool interfaces, state management, and failure handling
Build ML systems with disciplined training, evaluation, deployment, and safety practices
Design APIs that are stable, ergonomic, and evolvable
Design systems at the right scale with explicit trade-off documentation
Design services that are reliable, observable, secure, and maintainable
| name | spec-driven-development |
| description | Write a specification before writing any implementation code |
| difficulty | senior |
| domains | ["general"] |
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.
Write down what you've been asked to build, in plain English, without interpretation. Include the source (ticket, conversation, PR comment).
Answer: Who uses this? How do they know it works? What does failure look like?
List what the system must do. Use "The system shall..." or "When X, then Y." Each requirement must be independently testable.
Document: performance expectations, security constraints, accessibility requirements, scale targets, error handling expectations.
Sketch the inputs, outputs, and state transitions. Identify what data must be stored, what must not be stored, and what can be computed.
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.
Document every assumption you made and every question you don't have an answer to. Get answers before writing code.
Have the spec reviewed by at least one stakeholder before starting implementation. A spec that nobody reads is not a spec.
"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.
Before starting implementation:
