01
Specs before code
Every non-trivial change begins with a written spec — the constraints, the failure modes, the acceptance criteria. Code follows the spec, not the other way around.
Placeholder method entry. Rewrite the body before launch.
We do not start a feature, a refactor, or a migration without a one-page spec. The spec names the user, names the constraint, names the failure mode that makes the change worth doing, and names the acceptance criteria. The spec lives in the repo, not in a ticketing tool.
Specs are short. A spec longer than a page usually hides an unresolved question — answer it before writing code, not during code review.
The spec is also the brief we hand to Claude Code. A clear spec produces a clear draft; a vague spec produces an expensive rewrite.
Why
Engineers write better code under explicit constraints. Agents do too. Skipping the spec front-loads the work into PR review, which is the most expensive place to discover that the requirements were wrong.
How we do it
- Spec is checked into
/specs/{slug}.mdbefore the branch is created. - Spec is reviewed by one peer in under 30 minutes — async, not in a meeting.
- Once the spec is merged, the implementation is allowed to start.
- If the spec turns out to be wrong, we update the spec, not the code.