spec-driven-development

Start by listing your assumptions explicitly, then write a spec covering six areas: objective, commands, project structure, code style, testing strategy, and boundaries. Reframe vague requirements into specific, testable success criteria and get human approval before implementing.

Decompose when a single requirement bundles several independently testable capabilities, such as identity, billing, and notifications. Create a small module table with stable kebab-case ids, one-way dependencies, and a build order, then get it reviewed before writing any module spec.

Skip the full spec process for single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained. Even simple tasks benefit from a two-line spec with acceptance criteria, but the gated workflow is unnecessary overhead for trivial changes.

Treat the spec as a living document: update it when decisions or scope change, commit it to version control alongside the code, and reference spec sections in pull requests. Update the spec first, then implement the change.

Without a spec, implicit assumptions about requirements go unchecked until code review or production. A short spec surfaces misunderstandings before implementation, turning vague requests like "make it faster" into measurable targets such as LCP under 2.5 seconds.