Planning and Reflection

ReAct is step-by-step. But some problems need the agent to think bigger before acting. That's where planning and reflection patterns come in.

Plan-Then-Execute

The agent generates a full plan before taking any action:

Plan:

Read the existing auth middleware
Identify where session tokens are stored
Write new middleware that uses encrypted cookies instead
Update all routes that reference the old middleware
Write integration tests
Run tests and iterate


Executing step 1...

This is Claude Code's plan mode. You explicitly ask it to think before acting. The tradeoff: more upfront reasoning cost, but fewer wrong turns.

When to use it: Complex tasks touching multiple files, architectural changes, anything where a wrong first step would cascade into wasted work.

When to skip it: Simple fixes, single-file edits, tasks where the path is obvious.

Self-Reflection

The agent periodically stops and evaluates its own progress:

[After 5 actions]
Reflection: I've been editing test files but haven't actually run the tests yet.
I should verify my changes work before continuing to the next file.
Let me run the test suite now.

Self-reflection prevents drift. Without it, agents can spend 20 actions going in the wrong direction before discovering the error.

In Claude Code, extended thinking serves as a reflection mechanism. Before each action, the model can reason about whether its approach is working.

Task Decomposition

Breaking a complex goal into subtasks, then solving each:

Goal: "Build a client reporting dashboard"

Subtasks:
├── Data layer: Connect to PostHog API, fetch key metrics
├── Processing: Calculate week-over-week changes, identify anomalies
├── Presentation: Generate markdown report with charts
└── Delivery: Send via Slack to client channel

This is hierarchical planning — each subtask might itself be decomposed further. The agent works on one subtask at a time, keeping the big picture in mind.

Your TodoWrite tool in Claude Code is exactly this pattern: the agent decomposes the task into checkable items and works through them sequentially.

The Planning Overhead Problem

Planning has a cost. For simple tasks, it's pure overhead:

• "Fix the typo in README" → Just fix it. No plan needed.
• "Refactor the authentication system" → Plan first. Definitely.

The decision boundary: will a wrong first step cost more to undo than the planning cost? If yes, plan. If no, just start.