# Spec-Driven Development with Claude Code in Action



I'm building a [simplified sync engine from scratch](https://github.com/alexanderop/nuxt-sync-engine) using Nuxt 4.
My approach: study how production-grade frameworks solve the hard problems, then implement a minimal version myself.

[Jazz](https://jazz.tools) is my primary reference a local-first framework with elegant patterns for persistence, conflict resolution, and cross-tab sync. Rather than reading through their codebase manually, 
I use Claude Code to research, extract patterns, and help me implement them.

This post documents the workflow I call **Spec-Driven Development with Claude Code** the exact prompts, tools, and patterns I used to migrate my storage layer from SQLite/WASM to IndexedDB in a single day.

## The Problem

My sync engine was using `sql.js` (SQLite compiled to WASM) for client-side storage. It worked, but had issues:
- Large WASM bundle (~1MB)
- Complex COOP/COEP header requirements
- No native cross-tab sync

I wanted to migrate to IndexedDB, borrowing patterns from Jazz. But this was a significant refactor touching 15+ files. (For background on <InternalLink slug="what-is-local-first-web-development">local-first web development</InternalLink> and why it matters, see my earlier post.)

## The Workflow

Instead of diving into code, I used Claude Code as an **AI development team**with myself as the product owner, Claude as the tech lead, and subagents as developers.

Important: I also cloned the source code of Jazz into my Project so Claude could reference it during research and implementation.

<Figure
  src={specDrivenDevelopmentImg}
  alt="Spec-Driven Development workflow: Research Phase with parallel subagents, Spec Creation with written document, Refine with Q&A interview pattern, and Implement with task-per-subagent"
  caption="The four phases of Spec-Driven Development with Claude Code"
/>

## Phase 1: Research with Parallel Subagents

### The Prompt

<Prompt>
you have access to jazz source repo explain to me how they use
indexdb in the client to persist state our project is using sqlite
but we want to change to indexdb with jazz your goal is to write
a report spin up multiple subagents for your research task
</Prompt>

### What Happened

Claude spawned **5 parallel research agents**, each investigating a specific aspect of Jazz:

<Figure
  src={researchPhaseImg}
  alt="Research Phase: Five parallel agents (CRDT, WebSocket, Push/Pull, Storage, Architecture) each investigating independently, converging into a consolidated research report"
  caption="Parallel research agents converging into a consolidated report"
/>

Each agent explored the Jazz codebase independently and reported back:

| Agent | Focus | Key Findings |
|-------|-------|--------------|
| CRDT | Data structures | CoMap, CoList use operation-based CRDTs with LWW |
| WebSocket | Real-time sync | 4-message protocol: load, known, content, done |
| Push/Pull | Sync strategy | Hybrid model with known-state tracking |
| Storage | Persistence | IndexedDB with `coValues`, `sessions`, `transactions` stores |
| Architecture | Overall design | Monorepo with platform adapters |

### Follow-up Prompt

<Prompt>
research longer and improve the plan
</Prompt>

This triggered deeper investigation into edge cases and implementation details.

## Phase 2: Spec Creation

After research, Claude wrote a comprehensive technical specification to `docs/indexeddb-migration-spec.md`:
[Full spec](https://gist.github.com/alexanderop/70ef80ac6dda5166c5085cc9bb269df1)

```markdown