New feature plan
Imagine it this way: You're going to build a new room in your house. Without a blueprint, the plumbing might not reach it. With a blueprint, everything connects. For new features, the plan ensures the new functionality fits into the existing architecture.
A new feature is where plan mode shines most. The ideal prompt includes what the feature does, which components it touches, which patterns the project already follows, and how to validate that it works. The more context you provide, the more precise the plan will be.
The secret is to be specific about the constraints: "follow the existing auth middleware pattern," "use the same testing style as user.test.ts," "don't create new config files." Clear constraints produce plans that fit the project instead of inventing a new architecture.
In one sentence: for new features, with context about existing constraints and patterns; the plan falls into place on its own.
Refactor plan
Imagine it this way: You want to replace the floor in your house without tearing down the walls. You need to know the order: move the furniture, remove the old flooring, install the new flooring, move the furniture back. Refactoring works the same way: the order of the steps is everything.
Refactors are dangerous without a plan because they affect existing code that works. The ideal prompt asks Claude to map all dependencies of the code to be refactored first. What calls this function? What imports this module? Which tests cover it?
The safest technique is incremental refactoring: ask for a plan that changes one thing at a time, running tests between each step. If a step breaks something, you know exactly where to roll back. The plan should include a "step zero" snapshot (commit or stash) before starting.
In one sentence: refactors call for an incremental plan with tests between each step and a snapshot before starting.
Bug fix plan
Imagine it this way: A detective doesn't start by arresting suspects. They investigate, gather evidence, build a theory, and only then act. Bug fixing is an investigation: reproduce, diagnose, fix, validate.
The most common mistake in bug fixes is jumping straight to the fix without understanding the root cause. The ideal plan starts with: (1) reproduce the bug, (2) identify the cause, (3) propose a fix, (4) add a regression test. Asking for this explicitly in the prompt ensures Claude doesn't skip steps.
Tip: include the exact error message in the prompt, the expected versus actual behavior, and which hypotheses you've already ruled out. This saves back-and-forth rounds and lets the plan start at the right point.
In one sentence: bug fix = reproduce, diagnose, fix, test. Always in that order.
Each type of plan has its own structure, but they all converge on the same pattern: context, constraints, and steps.
Worked example: bug fix plan
Bug: "checkout page freezes when user has an expired coupon".
Step 1: Reproduce — open checkout with expired coupon, confirm the freeze.
Step 2: Diagnose — the error is in coupon.validate(), which returns undefined instead of error.
Step 3: Fix — add a guard clause to coupon.validate() for expired coupons.
Step 4: Test — add a test case for an expired coupon in checkout.test.ts.
Going deeper (optional): when should you decompose vs. keep it monolithic?
If the task has linear dependencies (A before B before C), keep it in a single sequential plan. If it has independent parts that can run in parallel, break it into subplans. The rule: break it down when the parts can fail independently.
Task decomposition
Imagine it this way: Eating a whole ox is impossible. Cutting it into steaks is easy. Decomposition means cutting a large task into pieces small enough to bite off.
When a task is too large for a single plan, break it down into independent subtasks. Each subtask should be verifiable: you can say “this works” or “this doesn’t work” without depending on the others.
The practical rule: if a plan step has more than 3 substeps, it probably needs to be broken down. Ask Claude: "break step 3 into atomic subtasks". Atomic = a single change with a single success criterion.
In one sentence: break it down until each step has a single verifiable success criterion.
Mapping dependencies
Imagine it this way: You can't put the roof on before the walls. Dependencies are the natural order of things: what needs to exist before something else.
A plan without mapped dependencies is a shopping list, not a plan. Claude needs to know which steps depend on others, which can run in parallel, and which are blockers. Ask explicitly: "map the dependencies between the steps".
Visualize it as a graph: if step C depends on A and B, then A and B can be done in any order (or in parallel), but C starts only after both are complete. This is especially useful when you combine plan mode with loop mode in module 2.5.
In one sentence: without mapped dependencies, the plan is just a list; with them, it's a critical path.
Effort estimate
Imagine it this way: A construction budget doesn't have to be exact, but it has to exist. If the builder says "about 3 days" and it's already been 10 days, something went wrong. Tokens and time are the same.
Before approving the plan, estimate: how many tokens it will use, how long it will take, and how many iterations will probably be needed. It doesn't need to be precise. An order-of-magnitude estimate already helps: "is this 5 minutes or 2 hours?".
Useful heuristics: each edited file consumes ~2-5k context tokens. A test loop typically needs 3-7 iterations. If the plan has more than 10 steps, consider splitting it into two separate plans. If the estimate feels daunting, simplify the plan.
In one sentence: Estimate tokens, time, and iterations before approving. If it looks daunting, simplify.
# Feature nova "Plan: adicione endpoint POST /api/invoices que cria fatura. Siga o pattern de /api/orders. Inclua validacao de input, testes e migration de DB." # Refactor "Plan: refatore o modulo de notificacoes para usar o pattern Observer. Mantenha a interface publica igual. Rode testes entre cada passo." # Bug fix "Plan: o upload falha para arquivos >5MB. Erro: 'PayloadTooLargeError'. Reproduza, identifique a causa, corrija e adicione teste de regressao."
What’s the safest technique for planning a refactor?
Module Summary
Next module:
2-3 — Loop Mode — Iterative Automation: how Claude runs in an autonomous loop.