Write the Spec First
Published: 13 May 2026
Tagged: Thoughts

I typed: “Add biometric authentication with token refresh”. The AI built it. It ran. Unit tests passed. Then code review happened — and the whole thing had to be thrown out. No one had talked about the existing Keychain wrapper, the token rotation strategy already in place, or that BiometricService was already handling the LAContext lifecycle.

The code was correct. The spec was missing.

The Pattern Everyone Hits

AI coding agents are fast. Dangerously fast. You describe a feature in a sentence, and within seconds you have a full implementation — view models, services, tests.

The problem: the AI implements what it guesses you want, not what you actually want. And the gap between those two things is where all the rewrites live.

It has a name now: context collapse. The moment the agent forgets what it was supposed to be building — because the context window filled up, or because the original intent was never precise enough to survive the session.

Spec-Driven Development

The fix isn’t a better prompt. It’s a better spec.

Spec-Driven Development (SDD) flips the workflow: instead of jumping straight to “implement this”, you write a structured spec first — what we’re building, why, and the constraints. Then the AI implements against that spec.

The workflow has four phases:

  1. Specify — write the spec in markdown, stored in the repo
  2. Plan — AI breaks the spec into tasks
  3. Review — tasks are validated by a human
  4. Implement — AI writes code against the approved task list

You own the spec. The agent owns nothing — it just implements.

What a Spec Looks Like

A spec isn’t a novel. It’s a short markdown file — what we’re building, the constraints, and the decisions that aren’t obvious from the code.

## Feature: Biometric Authentication

### Goal
Add Face ID / Touch ID login using the existing `BiometricService`.

### Constraints
- Must use existing `KeychainWrapper` for token storage
- Token refresh handled by `AuthInterceptor` — do not duplicate
- LAContext lifecycle is managed by `BiometricService` — do not create new instances
- No new dependencies

### Out of scope
- Passcode fallback UI (separate ticket)
- Android biometrics

That’s it. Five lines of constraints. But now the AI has a contract, not a wish.

The Shift

Vibe coding felt like magic when it worked. But as the codebase grows, prompts get longer, the agent starts contradicting itself, and you spend more time debugging AI output than writing code.

Spec-driven development doesn’t remove AI from the loop. It gives AI something solid to work against. Tools like GitHub Spec Kit are already making this a first-class workflow.

The new developer role isn’t typing code. It’s writing specs and reviewing implementations. That’s the job now.