What this chapter teaches you: the 2-document planning method that turns a vague idea into a delivered feature with no surprises. It's what separates a random outcome from a predictable one. Reading time: 10 minutes.
Why it's non-negotiable
The biggest beginner mistake: directly asking "build me this feature". Without a plan, Claude will:
- Make technical choices without consulting you (and you'll find out too late)
- Potentially break existing functionality without realizing it
- Produce something that doesn't match your vision because it interpreted things differently
- Force you to redo everything, losing the work already done
The magic ratio: 10 minutes of planning = 2 hours of rework avoided. This ratio has been verified across dozens of features built.
The 2-document method
Document 1, the Design Doc (the WHAT)
This is the product vision. It answers: what are we building, for whom, and why?
You start with a brainstorm:
"Brainstorm a publishing streak system. Context: freelancers publish 1-2 times then quit. I want a gamified system that pushes them to publish regularly."
Claude will propose 3-4 approaches with the pros and cons of each:
Daily streak (Duolingo style)
→ Simple to understand but punitive, one missed day = everything lost. Not suited for freelancers who don't have time to publish every day.
Weekly streak (recommended by Claude)
→ More flexible, suited to the freelancer pace (1-2 posts/week). Tolerant on days but demanding on consistency.
Points + levels system
→ Rich gamification with visible progression, but more complex to implement and potentially distracting from the core of the app.
You're the one who chooses. This is where your domain knowledge makes all the difference, you know what will motivate your users. Claude then writes the final design doc with your choice.
What the design doc contains
- Problem: why this feature is needed
- Chosen solution: the selected approach with justification
- User stories: what the user sees and does at each step
- Business rules: the precise logic (e.g. "a streak breaks if no content is published for 14 days")
- Out of scope: what we're NOT doing in this version (important to avoid scope creep)
Document 2, the Implementation Plan (the HOW)
This is the technical roadmap. It answers: which tasks, in what order, with which checks?
You ask:
"Write the detailed implementation plan for the weekly streak. List each task with the files to create or modify, the verification commands, and the execution order."
Claude produces a numbered plan:
Task 1: SQL Migration, create the streaks table with columns user_id, current_streak, best_streak, last_publication_date
File: supabase/migrations/20260301_streaks.sql
Check: npx supabase migration up --local
Task 2: Regenerate the TypeScript types
Command: npx supabase gen types typescript --local > src/lib/types/database.types.ts
Check: npm run typecheck
Task 3: Server Action, calculate and update the current streak
File: src/lib/actions/streak.ts
Check: npm run typecheck && npm run lint
Task 4: UI Component, animated flame + counter
File: src/components/dashboard/publishing-streak.tsx
Check: npm run typecheck + check visually
Task 5: Dashboard integration
File: src/app/app/page.tsx
Check: verify visually on localhost:3000
Task 6: Unit tests
File: tests/unit/actions/streak.test.ts
Check: npm run test
What makes a plan solid
- Each task has a single clear objective
- The order respects dependencies (database before business logic, logic before UI)
- Each task has a specific verification command
- Independent tasks are identified (can run in parallel)
Where to save the plans?
Create a docs/plans/ folder in your project. Name each file with the date and the feature name:
docs/plans/
2026-03-01-streak-design.md ← the design doc
2026-03-01-streak-plan.md ← the implementation plan
2026-02-28-notifications-design.md
2026-02-28-notifications-plan.md
These files act as living documentation for the project. When you wonder "why did we make this choice?", the answer is in the design doc.
Quick alternative: native plan mode
For medium-sized features, Claude Code includes a native plan mode that avoids creating separate files:
- Shift+Tab in the chat to activate plan mode
- Or type
/planfollowed by your description
Claude produces a plan directly in the chat, waits for your validation, then executes. It's faster than the design doc + plan method for features that don't need durable documentation.
When to use what? Complex or structural feature → design doc + plan in
docs/plans/. Medium feature or fix → native plan mode (Shift+Tab).
Executing the plan
Once the plan is validated (whether in a file or in the chat), a single sentence is enough:
"Execute the plan in docs/plans/2026-03-01-streak-plan.md"
Claude reads the plan, executes each task sequentially, checks between each step, and asks for your validation at key moments (typically: UI design choices, ambiguous business logic).
You supervise instead of piloting line by line. It's the difference between a manager who does the work themselves and a manager who delegates effectively.
Handling surprises during execution
Sometimes the plan doesn't survive contact with reality. Here's how to handle common cases:
| Situation | Reaction |
|---|---|
| A check fails | Claude fixes it automatically and retries. If it fails twice, it asks you for help. |
| You change your mind on a design | Say it right away. Claude adapts and adjusts the rest of the plan accordingly. |
| A task is more complex than expected | Claude breaks it into subtasks and continues. |
| You discover an unplanned need | Add it to the plan: "Add a task 7: send a congratulations email when the streak reaches 4 weeks." |
Takeaway: brainstorm → design doc → plan → execution. This sequence is unbeatable. It turns a vague idea into a delivered feature, predictable, and matching your vision.