The Problem With Starting at Code

Most developers start with code. The requirements are in their head, the design emerges as they type, and the documentation — if it ever exists — gets written after the fact.

This works for small changes. It fails for anything non-trivial.

The failure mode is subtle: you build something that works but doesn't quite solve the right problem. The feedback comes late — during code review, during testing, or worst of all, in production.

Specs as Thinking Tools

A spec is not documentation. It's a thinking tool. Writing a spec forces you to answer questions you'd otherwise discover mid-implementation:

  • What exactly is the goal?
  • What are the constraints?
  • What are the edge cases?
  • What decisions need to be made, and what are the trade-offs?

These questions are cheaper to answer in prose than in code.

My Spec Format

Every non-trivial piece of work gets a spec in docs/specs/:

# Feature Name

## Goal
One sentence. What does success look like?

## Context
Why are we doing this? What prompted it?

## Requirements
- Functional requirements (what it must do)
- Non-functional requirements (performance, security)

## Technical Decisions
- Approach chosen and why
- Alternatives considered and why they were rejected

## Open Questions
- Things we don't know yet
- Decisions deferred until we have more information

Specs With AI Assistants

Specs become even more valuable when working with AI coding assistants. A good spec gives Claude:

  1. Clear scope — what to build and what not to build
  2. Decision rationale — why certain approaches were chosen
  3. Acceptance criteria — how to verify the work is correct

Without a spec, you're relying on Claude to infer all of this from a brief prompt. Sometimes it gets it right. Often it doesn't.

The Spec-Plan-Code-Verify Loop

My workflow follows a strict sequence:

  1. Spec — Define what we're building and why
  2. Plan — Break the spec into implementation steps
  3. Code — Execute the plan
  4. Verify — Confirm the code satisfies the spec

After implementation, the spec gets updated with lessons learned. It becomes a living document that captures the evolution of the solution.

When to Skip the Spec

Not everything needs a spec. Simple bug fixes, one-line changes, and well-understood modifications can go straight to code. The rule of thumb: if the change takes longer to spec than to implement, skip the spec.

Conclusion

Specs are the cheapest form of iteration. A paragraph rewritten costs nothing. A feature rewritten costs days. Write the spec first.