Spec-First AI Development: The Workflow Behind a One-Person Engineering Team

The problem

This book hands you a five-phase spec-first workflow — Discover, Research, Plan, Implement, Retrospective — plus two ready-to-use templates, drawn from an eighteen-month production run that shipped 9 platforms and 300+ passing end-to-end tests with 69.5% code sharing across two competing payment protocols on a $1,800 build budget. One person plus AI agents produced that output, and the gap between that and a solo developer shipping buggy AI code is the workflow, not the model.

You can prompt an AI coding agent to generate a function and get good code in seconds. You can prompt it to refactor a module and watch it touch six files cleanly. Then you ask it to add webhook retry logic to a Stripe integration and it produces an exponential backoff that does not honor the existing idempotency-key cache, silently drops the dead-letter case, and breaks an unrelated test that depended on a side effect the agent did not notice. The output looks correct. The integration fails in production three days later.

This is not an AI quality problem. The 84% of developers who use AI coding tools weekly are not getting different models than the 16% who do not. They are giving the model different instructions. Studies show 48% of AI-generated code contains security vulnerabilities — not because the model is incapable, but because the directing prompt was ambiguous, incomplete, or contradictory. The model did exactly what it was told. The problem was what it was told.

The team that shipped this article — over 300 passing end-to-end tests, production cryptographic transactions, 69.5% code sharing across two competing payment protocols, $1,800 build budget — was one person plus AI agents. The multiplier was not “smart enough” AI. It was a workflow that turns ambiguous human intent into precise, verifiable instructions an AI agent can execute reliably. This walks through that workflow.

What most people get wrong

Mistake one: writing the spec alone and handing it to the AI. This is the most common failure mode. You sit down for an hour, draft a requirements document, paste it into the agent, and tell it to implement. The result is a literal interpretation of every ambiguity in your spec. Humans are remarkably bad at specifying what they want on the first try. We think in concepts, not contracts. “I want a search feature” actually means “find products by name, category, and price range, with results ranked by relevance and purchase history, paginated at 20 items, with faceted filtering” — six requirements you forgot to write down. A human colleague fills the gaps from context. An AI agent has only what is in the context window. The spec written alone always ships the holes.

The Discover phase exists specifically to prevent this. Spec creation is a dialogue. State the intent with explicit uncertainty markers (“I think we need exponential backoff, but I’m not sure about the right max retry count”). The agent challenges assumptions, surfaces edge cases, and asks the clarifying questions a domain colleague would ask. The output is an intent artifact that contains the requirements you forgot, the constraints you did not name, and the open questions you have not yet decided.

Mistake two: implementing in the same context window where you planned. By the time you finish a planning session, the context is at 35% utilization and full of half-decisions, abandoned branches, and stale assumptions. Continuing into implementation in the same session means the agent carries all that noise into the build. The agent loses focus, repeats work, and starts hallucinating file paths from a half-remembered earlier turn. The fresh-context principle: implementation runs in a new session with only the Research file and the Plan file loaded. Context utilization starts at zero, stays well under 40%, and the agent reasons with only the information needed for the current step.

A working approach

Five phases. The first three converge the human-AI understanding before any code is written. The fourth executes. The fifth closes the loop:

1. Discover (Phase 0) — co-create the intent through dialogue. State what you want, state the uncertainties, let the agent challenge assumptions. Capture the result as an intent artifact: What it does, What it does NOT do, Key decisions, Open questions.
2. Research (Phase 1) — map the system before changing it. File paths with line numbers, data flow, dependencies, side effects. Output: a research file with the concrete coordinates of every file the change will touch.
3. Plan (Phase 2) — design the changes explicitly. Changes by file, implementation order, code snippets for tricky parts, acceptance criteria tied back to the spec. Human review at this gate is mandatory.
4. Implement (Phase 3) — execute in fresh context. Load only the research + plan files. Commit after each logical unit. Update plan progress as steps complete.
5. Retrospective (Phase 4) — classify every issue as a spec gap (update the spec), an agent deviation (update the prompt or CLAUDE.md rule), or a harness gap (add a test, linter, or CI gate). Improvement compounds.

A real Discover output looks like this:

## Feature: Webhook Retry System

### What It Does
- Retries failed Stripe webhook deliveries with exponential backoff
- Records all attempts for observability
- Routes permanently failed webhooks to dead-letter queue for manual review

### What It Does NOT Do
- Does not retry webhooks that fail validation (invalid signature = permanent reject)
- Does not modify the Stripe webhook endpoint itself (only internal processing)

### Key Decisions
- Max retries: 5 (Stripe's own retry window is ~72 hours; our retries are first hour)
- Base delay: 1 second (1s, 2s, 4s, 8s, 16s)
- Idempotency: Use existing KV-based idempotency keys (24h TTL) from nonce service
- Alerting: Slack notification after 3rd failure, PagerDuty after final failure

### Open Questions
- Should we reconcile with Stripe's payment list API as a daily batch job?
  (Deferred to separate feature)

The research phase output sits in .claude/doc/research-{topic}.md. It contains the concrete file coordinates the agent will need:

## Affected files
- `apps/api/src/webhooks/stripe.ts:45-89` — current webhook handler
- `apps/api/src/services/idempotency.ts:12-44` — KV-backed idempotency cache
- `apps/api/src/services/dead-letter.ts:1-30` — DLQ wiring (currently unused for webhooks)
- `apps/api/supabase/migrations/0042_webhook_log.sql` — webhook log table

## Data flow
1. Stripe POST → /webhooks/stripe → verifyHmac()
2. On success: dispatch to internal handler queue
3. On internal handler failure: currently silently drops (the bug)

The plan file lives next to the research file. The implementation session starts fresh and loads both. Commits land every logical step. The retrospective at the end classifies every bug discovered against one of the three buckets and updates the right artifact.

The CLAUDE.md file is the connective tissue. It contains the rules that the agent must follow on every session — “use the knowledge graph for discovery”, “never trust client-sent commission amounts”, “always commit after each logical unit”. A starter CLAUDE.md is included with the book; the rules grow as the retrospective surfaces patterns worth codifying.

Where this scales

The walkthrough above is the workflow spine. The full book covers six more dimensions:

• The Anti-Pattern Gallery — SpecFall (waterfall with extra steps), context overload (the 100% trap), plan drift (the evolving target), solo-spec waterfall, the brownfield bypass, and premature implementation. Six failure modes with the diagnostic signal each one produces.
• Phase-specific templates — Discover template, Research template, Plan template, all in the bonus folder. Drop into a new session and the agent already knows the expected output shape.
• Brownfield rules — when you are modifying an existing system without spec coverage, write the spec for that area first. The full chapter on how to bootstrap specs into an existing codebase without rewriting everything.
• The knowledge graph advantage — what changes when your research file is generated from a knowledge graph query rather than ad-hoc Grep. Faster research, fewer missed files, and a discovery surface that improves as the graph grows.
• Team adoption strategies — solo developer, small team (2–5), enterprise. The friction points at each scale and the order of operations that works.
• Measuring success — the metrics that tell you the workflow is working. Bugs per feature, retrospective signal-to-noise ratio, decision-record growth rate, and the leading indicator: time from intent to merged PR.

Every pattern in the book has been tested in production over the eighteen-month period that produced 9 platforms, 300+ E2E tests, and the 69.5% code sharing figure across AP2 and ACP. The 5x team multiplier is a measured outcome, not an estimate.

Included with the book

• CLAUDE-starter.md — a production-shaped CLAUDE.md file with the rules that survived eighteen months of iteration. Drop into your repo as .claude/CLAUDE.md and start with the discipline already wired in.
• SPEC-template.md — the spec template every feature in the Pragma.Vision ecosystem uses. WHAT, WHAT-NOT, key decisions, open questions, acceptance criteria. Replaces the first hour of every new feature’s Discover phase.

Get the full picture

Readers of this also chose

Questions readers ask

Does this only work with Claude Code, or does it apply to Cursor and Copilot?

It applies to any AI coding agent that takes a prompt and edits files. Claude Code is the reference implementation in the book because we use it daily, but the workflow is tool-agnostic. Cursor, Copilot Chat, Aider, Continue — they all benefit from intent artifacts, research files, and explicit plans. The CLAUDE.md file is a convention; other agents look for their own equivalents (.cursor/rules, .aiderrules).

Is this just waterfall with extra steps?

No, and the difference is the dialogue. Waterfall hands a complete spec off and forbids re-opening it during implementation. Spec-first reopens the spec whenever the retrospective surfaces a gap. The phases are sequential per cycle but the loop is short — a feature takes one or two cycles, not a release-quarter waterfall.

What about TDD?

TDD slots in cleanly. Acceptance criteria in the Plan phase become test cases in the Implement phase. The retrospective classification ("harness gap") is the trigger for adding tests that would have caught the bug — exactly the TDD discipline applied to spec failures rather than code failures.

How long does the Discover phase take in practice?

For a typical feature, 15–30 minutes of dialogue. For an architectural decision, 1–3 sessions across a few days. The dual-protocol payment system in this book's case study took three Discover sessions and saved 1,180 lines of duplicate code that the naïve two-codebase shape would have shipped.

What's the refund policy?

Lemon Squeezy's standard refund window applies. The refund link is in the receipt email.