Planning with TodoWrite

What You’ll Learn

Complex tasks need a plan. When you ask Claude Code to “add authentication to my app,” it doesn’t just start editing random files. It creates a plan first.

By the end, you’ll understand:

• Why planning before execution matters
• How TodoWrite creates structured task lists
• The plan-execute-verify pattern
• How to use planning mode effectively

The Problem

Without planning, AI agents fall into common traps:

1. Tunnel vision — Starting with the first file that comes to mind, missing the bigger picture
2. Incomplete solutions — Fixing one part but forgetting related changes
3. Wasted effort — Going down wrong paths, then backtracking

Planning solves these by forcing a “think before you act” phase.

How It Works

The TodoWrite Tool

Claude Code has a built-in TodoWrite tool for creating and managing task lists:

┌─────────────────────────────────────────┐
│           Planning Flow                  │
│                                          │
│  User: "Add user authentication"         │
│       │                                  │
│       ▼                                  │
│  ┌──────────────┐                        │
│  │  Create Plan  │ ◄── TodoWrite         │
│  │  via TodoWrite│                       │
│  └──────┬───────┘                        │
│         │                                │
│         ▼                                │
│  ┌──────────────────────────────┐        │
│  │ Tasks:                       │        │
│  │ □ Research existing auth     │        │
│  │ □ Create auth middleware     │        │
│  │ □ Add login/signup routes    │        │
│  │ □ Update database schema     │        │
│  │ □ Add session management     │        │
│  │ □ Write tests                │        │
│  └──────┬───────────────────────┘        │
│         │                                │
│         ▼                                │
│  Execute each task sequentially          │
│  ✓ Research existing auth                │
│  ✓ Create auth middleware                │
│  → Add login/signup routes               │
│  □ Update database schema                │
│  □ Add session management                │
│  □ Write tests                           │
│                                          │
└──────────────────────────────────────────┘

Task Structure

Each task has:

interface Task {
  id: string;
  content: string;         // What to do
  status: 'pending' | 'in_progress' | 'completed';
}

The AI creates tasks with TodoWrite, then updates their status as it works through them. This gives both the AI and the user visibility into progress.

The Plan-Execute-Verify Pattern

The most effective pattern for complex tasks:

Phase 1: PLAN
  └── Analyze the request
  └── Break into discrete tasks
  └── Identify dependencies
  └── Create TodoWrite list

Phase 2: EXECUTE
  └── Work through tasks sequentially
  └── Mark each as in_progress → completed
  └── Adapt plan if surprises arise

Phase 3: VERIFY
  └── Review all changes
  └── Run tests
  └── Confirm nothing was missed

Planning Mode

Claude Code’s --plan flag forces a planning-first approach:

claude --plan

In plan mode:

• The AI must present its plan before executing
• Each tool call requires user approval
• The user can modify the plan before execution starts

This is especially useful for:

• Large refactors where you want to review the approach
• Unfamiliar codebases where you need to understand before changing
• Risky operations where mistakes are costly

Key Insight

Planning isn’t just about organizing work — it’s about making the AI’s reasoning visible.

When Claude Code creates a TodoWrite list, it’s essentially showing you its thinking. You can review the plan, catch misunderstandings early, and redirect before any code changes happen.

This is why experienced users often start complex tasks with “first, create a plan” — it’s not about micromanaging the AI, it’s about alignment. Better to catch a wrong assumption in the planning phase than after 20 files have been modified.

Hands-On Example

Try this prompt pattern for planning-first development:

I need to add a notification system to our app.

Before writing any code:
1. Explore the existing codebase to understand the architecture
2. Create a detailed plan using TodoWrite with all necessary tasks
3. Present the plan for my review before proceeding

Focus areas:
- Database schema changes needed
- API endpoints to create
- Frontend components to build
- Tests to write

This prompt structure ensures:

• Exploration happens before planning
• Planning happens before execution
• You review before any changes

Monitoring Plan Progress

During execution, you can check the plan state:

> Show me the current task list status

Tasks:
✓ Explore notification-related code
✓ Design database schema
→ Create notification model
□ Add API endpoints
□ Build notification component
□ Write integration tests

What Changed

Without Planning	With TodoWrite Planning
Jump straight to coding	Explore → Plan → Execute → Verify
Miss related changes	Dependencies identified upfront
No progress visibility	Task list shows status
Hard to review approach	Plan reviewable before execution
Backtracking common	Direction set before starting

Next Session

In Session 4, we’ll explore Subagents & Context Isolation — how Claude Code spawns child agents with clean message arrays to handle complex subtasks without polluting the parent context.