📝

The Three-Doc Method

A process for turning product ideas into something Claude Code can actually build — without session drift, scope creep, or three-week rewrites.

Most solo builds with Claude Code fail the same way. You have a clear idea, open a fresh session, describe the goal, and watch Claude Code start scaffolding. Three sessions in, the structure is wrong, the data model is an afterthought, and the hardest feature — the one the whole thing depends on — is bolted onto a foundation that can't hold it.

The root cause is not Claude Code. It's the handoff. Product visions and strategy notes don't compile. Claude Code needs three things before it writes a line of code: a spec tight enough to implement, an operating manual tight enough to stay on rails, and a first-session prompt tight enough to prevent scaffolding chaos. This method produces all three in a single focused chat before a single file is touched.

The Process

1
Open a fresh Claude chat — not Claude Code
Paste the scoping template (below). Describe the idea at the bottom. The template instructs Claude to push back hard, use web search if it sharpens the pushback, and ask up to three grouped clarifying questions if the idea has holes.
Why: a thinking-oriented Claude pushes back. An execution-oriented Claude Code does not. Strategy debate belongs here, not later.
2
Let Claude produce three files
Answer any clarifying questions. Accept the pushback on scope. The output is three Markdown files: SPEC.md, CLAUDE.md, and FIRST_SESSION.md.
Why: strategy is argued once and then closed. SPEC.md is the closed form of the argument.
3
Build a blank project in Xcode (or your equivalent)
Target, app delegate, build settings. No features. Just the shell on disk.
Why: gives Claude Code a real filesystem to reason about. Paths and targets are concrete before the docs land.
4
Open Claude Code and orient it
Ask Claude Code to read and understand the template project. Let it walk the tree.
Why: context priming. Claude Code reads CLAUDE.md knowing what actually exists, not as an abstraction.
5
Drop in the docs, paste the first-session prompt
Add CLAUDE.md and SPEC.md to the project root. Paste the contents of FIRST_SESSION.md into Claude Code.
Why: three sources of truth now align: the code template (what exists), SPEC.md (what to build), CLAUDE.md (how to build it).
6
Confirm v0 before a single line of code
Claude Code reads the docs, restates v0 in its own words, proposes the first 5 milestones with dependency reasoning, and waits. You confirm. Only then does code start.
Why: this is the single most important moment. It prevents session 1 drift, which is where most solo builds quietly go wrong.

What Each Doc Is For

SPEC.md

The buildable spec

Not strategy. A technical contract tight enough that Claude Code can implement without asking, and small enough that a working v0 exists in two to four weeks.

  • Scope — in and out, ruthlessly cut
  • Explicit non-goals
  • Target platform with exact OS version
  • Data model as actual code
  • State machines with legal transitions
  • Numbered screen or endpoint inventory
  • Hardest feature specified at 3x depth
  • File and project structure tree
  • Security posture for v0
  • Numbered manual test scenarios
  • Delivery criteria
  • Explicit deferred items
The question SPEC.md optimizes for: what is the minimum thing a tester can evaluate to tell me if this is worth building? Not: what is the product I imagine shipping.
CLAUDE.md

The operating manual

Re-read at the start of every session. This is how Claude Code stays on the rails across many sessions. Operational, not architectural.

  • What the project is and isn't
  • Who you are — communication preferences
  • Sycophancy named as a failure mode
  • Optimization priorities, in order
  • What you're not optimizing for
  • Technology choices table (decided)
  • Style and conventions
  • Data-sensitivity discipline
  • Session rituals — start, during, commit
  • Stack-specific gotchas
  • Escalate vs. don't-escalate lists
  • Per-session "done" criteria
If it belongs in SPEC.md, it doesn't belong here. CLAUDE.md is the rules of the road, not the destination.
FIRST_SESSION.md

The kickoff prompt

The exact text you paste into Claude Code for session 1. Its job is to install the alignment gate before any code exists.

  • Copy-pasteable opening message
  • Forces v0 restatement in Claude Code's own words
  • First 5 milestones with dependency reasoning
  • No coding until you confirm
  • Suggested 10-milestone order
  • Calendar-time estimate
  • Things to avoid in session 1
  • "Session went well" checklist
  • Between-session practices
This is the non-negotiable gate. Skip it and session 1 drift kills the build before you notice.

Why the Milestone Order Matters

  1. Data model and state machine first. Every screen, endpoint, and test depends on them. Getting them wrong later costs a rewrite.
  2. The hardest differentiated feature layers onto a stable foundation — never first. Building the hard thing on sand means rebuilding it on rock.
  3. One real feature end-to-end before any scaffolding sprint. Placeholder screens create false progress.
  4. No CI/CD before there is code to ship. No third-party dependencies before they're justified in writing. No comprehensive test suite before there is behavior worth testing.

Failure Modes This Method Prevents

Failure mode
What catches it
Session 1 drift — Claude Code starts coding before alignment
FIRST_SESSION.md forces a non-negotiable alignment gate.
Scope creep mid-build
SPEC.md has an explicit non-goals section. If it isn't listed, it isn't in v0.
Re-litigating tech choices every session
CLAUDE.md's technology table is the debate-ender. Point at it.
Sycophancy drift — Claude Code agrees with bad ideas
CLAUDE.md names sycophancy as a failure mode and specifies preferences.
Premature testing — comprehensive tests before behavior exists
Deferred-items list in SPEC.md plus explicit guidance in FIRST_SESSION.md.
Building the hardest feature first on an unstable base
Milestone order puts data model and state machine ahead of the differentiator.

What Good Looks Like

After the scoping chat

  • Three files exist: SPEC.md, CLAUDE.md, FIRST_SESSION.md
  • You can name the single most important interaction v0 has to get right
  • You can list three things explicitly out of scope
  • You know which screen or feature is hardest, and why

After session 1 with Claude Code

  • The app builds and launches
  • One screen is real — not a placeholder
  • Persistence works end-to-end for at least one entity
  • Commits are small and focused
  • A DecisionLog entry exists for any non-obvious choice
  • You were not asked to approve CI/CD, a dependency, or a test suite

The Scoping Template

Copy this and paste it into a fresh Claude chat. Describe your idea where it says [DESCRIBE YOUR IDEA HERE].

scoping-template.md 
I want you to help me turn this idea into something I can actually build with Claude Code. I've learned the hard way that strategy docs and product visions don't translate to code — what I need is a specific set of three artifacts.

Before you write anything, push back hard on the idea if it needs it. If the scope is too big for a solo founder with Claude Code, tell me. If there's a cheaper way to test the thesis, tell me. If an obvious competitor already solves this and I should pivot, tell me. I'd rather burn 20 minutes of conversation now than 3 weeks of building the wrong thing. Use web search if current market data would sharpen your pushback.

Once we're aligned on what's actually worth building, produce these three artifacts as separate files:

1. SPEC.md — the buildable spec
A technical spec tight enough that Claude Code can implement without ambiguity, and small enough that a working v0 exists in 2–4 weeks. Must include: scope (in and out, ruthlessly cut), explicit non-goals, target platform and exact OS version, data model as actual code (Swift structs / TS interfaces / SQL DDL / dataclasses — not pseudo-code), state machines with legal transitions, a numbered screen or endpoint inventory, the hardest screen or feature specified at 3x depth (ASCII wireframes welcome), file/project structure tree, security and compliance posture for v0 (honest about real vs. deferred), numbered manual test scenarios, delivery criteria (build time, warnings, bundle size, crashes), and an explicit deferred-items list.

Tone: direct, numbered, tabular where useful. No aspirational language. No marketing copy.

2. CLAUDE.md — the operational guide Claude Code reads every session
How Claude Code stays on the rails across sessions. Must include: what the project is and isn't, who I am and communication preferences (direct, no flattery, sycophancy named as a failure mode), optimization priorities in order, what we are NOT optimizing for, a technology choices table (decided, don't re-litigate), style and conventions, data-sensitivity discipline, session rituals (start, during, commit), stack-specific gotchas, explicit escalate / don't-escalate lists, per-session 'done' criteria.

Tone: operational, opinionated, scannable.

3. FIRST_SESSION.md — the kickoff prompt
What I paste into Claude Code for the first session. Must include: a copy-pasteable opening message that instructs Claude Code to read CLAUDE.md and SPEC.md, restate v0 in its own words, propose the first 5 implementation milestones with dependency reasoning, and NOT start coding until I confirm. Plus a suggested 10-milestone order with calendar estimate, things to avoid in session 1, a 'session went well' checklist, and between-session practices.

Tone: practical, checklist-heavy.

General expectations for all three files:
— Markdown, plain text. These get committed to repos.
— Numbered sections everywhere. Easy to reference as 'per SPEC §4.2'.
— Tables for lookups. Prose for rationale. Don't mix.
— No marketing voice. Ever.
— Reference each other. SPEC mentions CLAUDE.md discipline. CLAUDE.md points to SPEC as source of truth. FIRST_SESSION points to both.
— Explicit about what's NOT in the file.

If the idea is vague or has obvious holes, ask targeted questions — grouped, max 3 at a time — until you have enough to write a real spec. Common gaps: who the tester is, what platforms, the single most important interaction, whether sensitive data is involved, whether an obvious existing tool already does 80% of this.

Deliverables, in order:
1. Honest pushback and validation of the idea. Use web search if needed.
2. Any clarifying questions, if required.
3. SPEC.md, CLAUDE.md, FIRST_SESSION.md as three separate files.

Ready when you are. Here's what I want to build:

[DESCRIBE YOUR IDEA HERE]

When to Break the Method

This method is for products where the core value is contested and the scope is easy to get wrong — new apps, new workflows, anything with a novel interaction. For tightly scoped work where the spec is the request (a parser, a migration script, a data fix), the full three-doc ritual is overhead. Use judgment. The method is a tool, not a rule.