Claude Code planning mode: making the output reviewable, not just correct

On this page#

• What changes when an agent does this
• The prompt chain
• The gate
• What it gets wrong
• Rollback
• FAQ

What changes when an agent does this#

Claude Code planning mode moves the bottleneck from generating code to reviewing intent. The agent can produce a plausible implementation quickly; the harder job is proving that its proposed scope, assumptions, file changes, and validation steps preserve the repository’s invariants before anyone lets it edit the code.

That distinction matters in a real repository. “Correct” usually means the patch satisfies the request. “Reviewable” means a human can determine, before implementation, whether the agent understood the request at all.

A reviewable plan exposes:

• The behavior that will change—and what must remain unchanged.
• The files or components likely to be touched.
• The evidence behind each proposed change.
• The tests or checks that will prove the result.
• The assumptions that still require human confirmation.
• A rollback boundary that does not depend on remembering what the agent did.

Claude Code is an agentic coding tool: it can inspect a codebase, reason about a task, and carry out development work. Planning mode is useful because it separates investigation from mutation. That separation is necessary, but it is not sufficient. A long plan can still be vague, unauditable, or confidently wrong.

The right target is not “make a detailed plan.” It is “produce a plan that can fail review before the code fails production.”

Photo by Christina Morillo on Pexels.

The prompt chain#

Use a prompt chain that separates discovery, constraint extraction, plan construction, and adversarial review. Asking for everything in one prompt encourages the agent to collapse evidence and inference into polished prose, which makes unsupported assumptions harder to see.

Phase 1: Establish the operating boundary#

Start by preventing premature implementation:

Stay in planning mode. Do not edit files, generate a patch, or propose code yet.

Inspect the repository only as needed to answer:
1. Where does the current behavior live?
2. What entry points, callers, tests, schemas, and configuration constrain it?
3. Which repository conventions apply?
4. What information is still missing?

For every claim, name the file, symbol, test, or configuration that supports it.
Separate observed facts from assumptions.

This prompt forces provenance into the investigation. The important phrase is “separate observed facts from assumptions.” Without it, agents routinely present architectural guesses with the same confidence as facts read directly from code.

The official Claude Code documentation explains the product’s supported workflows and controls. Your repository prompt must add something more local: the invariants that no general-purpose documentation can know.

Phase 2: Extract invariants before choosing an implementation#

Once the agent has mapped the relevant area, ask it to state what cannot break:

From the evidence collected, list the invariants this change must preserve.

Group them as:
- externally visible behavior
- data and schema compatibility
- authorization or security boundaries
- failure and retry behavior
- performance-sensitive paths
- test and tooling expectations

Mark each invariant as confirmed or inferred. Do not design the solution yet.

This ordering is deliberate. If the agent proposes a solution first, it will tend to define the constraints around its preferred implementation. That is backwards.

An invariant is a property that must remain true across the change. Examples include preserving an API response shape, maintaining idempotency, or keeping an authorization check ahead of a write. Do not invent invariants merely to fill every category; an empty category is more honest than fictional certainty.

Phase 3: Produce a reviewable implementation plan#

Now ask for the plan:

Create an implementation plan using only the confirmed repository evidence and
the explicitly marked assumptions.

For each step include:
- intended behavioral change
- exact files or symbols likely to change
- why the change belongs there
- invariant protected by the step
- validation to run after the step
- dependencies on earlier steps

Also include:
- files inspected but intentionally left unchanged
- rejected alternatives and the concrete reason for rejecting them
- unresolved decisions that require human approval

This format makes each step independently challengeable. “Update the service and add tests” is not a plan step. It hides placement, scope, and proof.

If this discipline is new to the team, the free PairFoundry foundations track is the sensible next step. Teams ready for a reusable review workflow can use Review and Repair; the broader set is listed in the PairFoundry packs overview.

Phase 4: Attack the plan before approving it#

Finish with a separate review pass:

Review the proposed plan as a skeptical maintainer.

Identify:
- unsupported claims
- missed callers or integration boundaries
- steps that are too broad to review
- tests that could pass while behavior remains wrong
- changes that are unnecessary for the requested outcome
- assumptions that should block implementation

Return a revised plan, not a defense of the original.

This prevents the agent from treating its first coherent answer as settled. The workflow resembles code review, where another examination looks for defects and maintainability problems, but it moves that scrutiny earlier—before a patch creates momentum and review fatigue.

The gate#

The gate is a deliberate human stop between the final plan and any file modification. Approval must cover the plan’s evidence, scope, invariants, and validation—not merely whether the prose sounds reasonable.

At the gate, the reviewer should be able to answer five questions:

1. Does every proposed edit trace back to the requested behavior?
2. Are repository facts distinguishable from assumptions?
3. Is every important invariant attached to a validation step?
4. Are unresolved decisions visible and genuinely resolved?
5. Can the change be implemented in reviewable increments?

Use an explicit approval instruction:

Do not implement until I approve this plan.

Before requesting approval, provide:
- the final change boundary
- confirmed invariants
- unresolved assumptions
- ordered implementation steps
- validation commands or checks
- rollback units

If any assumption could change the architecture or public behavior, stop and ask.

The gate should reject speculative cleanup, unrelated refactoring, and “while we are here” changes. Those additions enlarge the review surface without improving confidence in the requested outcome.

Anthropic’s Claude Code overview describes the tool’s broader coding capabilities. The human gate is a repository governance layer: the tool can help execute work, but the maintainer still owns the decision that the proposed work is appropriate.

Photo by panumas nikhomkhai on Pexels.

What it gets wrong#

Planning mode fails most often by producing plans that are internally coherent but weakly grounded. The danger is not obvious nonsense; it is a smooth narrative that skips one caller, invents one convention, or validates the wrong behavior.

| Failure mode | How to recognize it | Required response | |---|---|---| | Architecture by filename | Claims rely on names rather than symbols, callers, or configuration | Demand repository evidence | | Happy-path planning | No failure, retry, authorization, or compatibility analysis appears | Re-run invariant extraction | | Test-shaped reasoning | The plan optimizes for existing tests instead of required behavior | Add behavioral acceptance checks | | Scope laundering | Refactoring is presented as necessary without a dependency chain | Remove or split it | | False precision | Exact files are listed without explaining why they own the behavior | Ask for symbol-level justification | | Confirmation lock | The agent defends its first plan instead of revising it | Start a skeptical review pass |

Another common failure is treating “read-only planning” as proof of safety. It only prevents premature edits. It does not prove the agent inspected the correct files, understood runtime wiring, or found implicit contracts.

The Claude Code documentation is authoritative for how Claude Code operates. It cannot document the unwritten constraints in your repository. If the plan cannot point to code, tests, configuration, or an explicit human decision, that part of the plan remains unverified.

More workflow patterns belong in PairFoundry’s workflows hub, but one rule is universal: never approve a plan because it is comprehensive-looking. Approve it because its claims are traceable and its omissions have been challenged.

Rollback#

Rollback should restore the last reviewed state in small, identifiable units. Do not ask the agent to “undo everything” from memory; define checkpoints before implementation and keep unrelated work outside the change boundary.

Before execution, require this:

Divide the implementation into independently reviewable units.

For each unit specify:
- files expected to change
- validation required before continuing
- observable behavior introduced
- how to revert only that unit
- whether later units depend on it

Do not mix unrelated cleanup into any unit.
Stop after a failed validation.

A clean rollback sequence is:

1. Stop at the first failed validation.
2. Record the failing behavior and the implementation unit that introduced it.
3. Revert only that unit.
4. Re-run the checks that passed at the previous checkpoint.
5. Re-plan from the newly discovered evidence.

Do not let the agent repair a failed implementation by stacking speculative edits onto it. That destroys causality. Return to the last known-good checkpoint, update the plan, and pass through the gate again.

This is where conventional code review and planning mode reinforce each other: the plan defines intent and boundaries, while patch review verifies that the implementation stayed inside them.

Photo by Christina Morillo on Pexels.

Related reading#

• Claude Code documentation — the workflow, the gate, and the rollback
• Claude Code security, with the guardrails that keep it honest

FAQ#

When should I skip this workflow?#

Skip the full chain for changes whose scope and proof are genuinely local, such as a narrowly bounded text correction. Do not skip it merely because the patch looks small; configuration, authorization, schema, and shared-library changes can have a tiny diff and a large behavioral radius.

How is this different from simply using Claude Code’s official planning workflow?#

The official workflow provides the mechanism for investigating and planning before implementation. This approach adds a stricter review contract: evidence for claims, explicit invariants, an adversarial plan review, a human approval gate, and rollback units. Those are repository controls, not product features described by general official documentation.

What is the biggest problem when a team adopts planning mode?#

Teams often approve plans based on readability instead of traceability. One engineer accepts an assumption, another interprets it as a confirmed repository fact, and implementation begins. Require file-, symbol-, test-, or configuration-level evidence, and assign one reviewer responsibility for resolving blocking assumptions.

What should I do when the agent’s implementation diverges from the approved plan?#

Stop implementation immediately. Do not retroactively edit the plan to legitimize the patch. Identify the first divergence, revert to the previous reviewed checkpoint, capture the new evidence that caused the deviation, revise the plan, and send it through the human gate again.

When is planning mode the wrong tool?#

It is the wrong tool when the real blocker is an unresolved product, security, or architecture decision. An agent can expose that decision and map its consequences, but it should not silently choose among materially different outcomes. Stop planning, get an accountable human decision, then resume.