Agentic Pattern Libraryby Vikas Goyal
← All patterns
44

Plan-then-Code

Also known as: plan mode, design-first coding, plan review

The agent proposes a plan; a human approves it before any files change.

TrackBuilding with coding agents FamilyBuild loop Maturity Established ChangesDecisionVerification
01

Problem

Given a task, a coding agent will often start editing files immediately. If it misread the task or picked a poor approach, you find out only after it has changed 20 files. Reviewing that diff is slow, and undoing a wrong direction costs more than the task itself.

  • Wrong approaches are cheapest to catch before any code exists.
  • Developers don’t want to approve every small step.
  • Plans can look reasonable and still miss the hard part.
  • Agents explore the codebase better when they aren’t also editing it.
02

Solution

For any task beyond a trivial edit, have the agent work in a read-only planning step first. It explores the relevant code, then writes a short plan: the approach, files to change, new tests, risks and open questions. The developer reviews the plan, corrects the approach or answers the questions, and approves. Only then does the agent switch to editing, following the plan. If reality differs from the plan mid-task, the agent stops and updates the plan instead of improvising a different design.

03

Diagram

Task Plan moderead-only Planapproachfiles to changetests · risksopen questions Developerreview Edit modefollow plan approve correct approach · answer questions reality differs→ stop, replan no files change before approval

Corrections are cheapest at the plan stage. A two-minute plan review often saves an hour of diff review and rework.

04

When to use

Use it when

  • Tasks touch several files or an unfamiliar part of the codebase
  • There's more than one reasonable approach
  • Mistakes would be expensive to unwind (schema, API, security changes)
  • You want to stay in control of design without writing the code

Avoid it when

  • One-line fixes and obvious changes
  • Pure exploration where you want the agent to try things quickly in a branch
  • When you'd approve without reading; then the plan is just overhead
05

Trade-offs

Latency A short planning and review step up front
Cost Avoids expensive wrong-direction runs
Complexity Most coding agents support a plan mode
Reliability Design mistakes caught before code exists

Gains

  • Wrong approaches caught before any code exists
  • The developer stays in charge of design decisions
  • The approved plan doubles as PR description and documentation

Costs

  • Adds a step to every non-trivial task
  • Plans can hide the hard part behind vague steps
  • Developers may rubber-stamp plans they didn't read
06

Worked example

Scenario
Linkwatch MVP2 adds Slack alerts alongside the existing log-file alerts.
  1. Agent (plan mode)Reads the alert code and config, and changes nothing. Proposes: add a SlackNotifier class next to LogNotifier, a webhook URL in config, retries in the notifier, 4 new tests.
  2. Open questionThe plan asks: “Should a Slack failure block the log-file alert?”
  3. DeveloperAnswers no, the notifiers must be independent. Also says to put both behind a Notifier interface so email can be added in MVP3. Approves the revised plan.
  4. Agent (editing)Implements the plan: 6 files changed and 5 tests added, all passing.
  5. ComparisonIn a test without planning, the agent wired Slack directly into the checker loop. Undoing that took longer than the whole planned task.
07

Failure modes

FailureSymptomMitigation
Vague plan"Update the alert logic" with no files or approachPlan must list files, approach, tests and open questions
Rubber-stamp approvalPlans approved in seconds; problems surface in reviewKeep plans short enough to actually read; review the risks section
Plan driftAgent quietly does something different from the planAgent must stop and update the plan when reality differs
Planning trivial tasksPlan reviews for one-line changesSkip planning below a size or risk threshold