Plan before coding

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 2-document method

Working example: a publishing streak system for freelancers. We'll walk it from brainstorm to executable plan.

Document 1, the Design Doc (the WHAT)

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 proposes 3-4 approaches with the pros and cons of each:

You choose. Your domain knowledge makes the difference, you know what will motivate your users. Claude then writes the final design doc with your choice.

What the design doc contains

Concrete example for the weekly streak:

• Problem: 80% of freelancers who sign up stop publishing after 2 weeks. We want to install a habit.
• Chosen solution: weekly streak, validated with 1 publication per week from Monday to Sunday.
• User stories: "When I publish content, my counter goes +1. When I hit 4 consecutive weeks, I get a badge. When I miss a week, the counter resets to 0 but I still see my best streak."
• Business rules: one week = Monday 00:00 to Sunday 23:59 (user timezone). The streak breaks if no valid publication over a full week.
• Out of scope: no leaderboards between users, no push notifications, no monetary rewards. Deferred to v2.

Document 2, the Implementation Plan (the HOW)

The technical roadmap. It answers: which tasks, in what order, with which checks?

You ask:

"Write the detailed implementation plan for the weekly streak described in docs/plans/2026-03-01-streak-design.md. List each task with the files to create or modify, the verification commands, and the execution order."

Claude produces a numbered plan:

What makes a plan solid

• Each task has a single clear objective
• The order respects dependencies (database before 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 /plan followed by your description

Claude produces a plan directly in the chat, waits for your validation, then executes. Faster than the design doc + plan method for features that don't need durable documentation.

Executing the plan

Once the plan is validated (file or 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. 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: