Does this not just slow everything down?

It front-loads the reading you were going to do anyway. The plan replaces a first pass over the diff; it does not add one.

What if the plan is wrong but the code is right?

Then you have learned the agent is guessing, which is worth knowing before it guesses about something you cannot check as easily.

Make the agent show its plan first

Require the agent to state its plan and the files it will touch before it edits any of them.

EngineersVibe codersanthropicopenai

A plan is reviewable in fifteen seconds; the diff it produces takes fifteen minutes. Reading the plan first is the highest leverage minute in the whole loop, because a wrong approach caught at the plan stage costs nothing and the same approach caught at review costs you the entire diff. It also converts a vague request into a list you can argue with.

What goes wrong: Forty files changed in service of a misunderstanding you could have corrected in one sentence.

What agents change: An agent's confidence is uncorrelated with its correctness, so the plan is the only cheap place to detect that it understood a different problem.

You are violating it when

You find yourself reverting a whole agent run rather than correcting part of it.
You cannot say which files a change touched without opening it.

The usual objection: That the thing to plan around is SIZE. It is ambiguity, and the two come apart: a one-line change to a pricing rule is small and highly ambiguous. Anthropic's own guidance says to skip planning when you could describe the diff in a sentence — that is the right carve-out, and it is a test of clarity, not of line count.

Before an agent edits, have it summarize the intended approach and name the files it expects to change. That turns an open-ended instruction into a small review artifact: the problem it thinks it is solving, the route it plans to take, and the blast radius it expects. The useful unit is not a formal design document; it is a short checkpoint before the repository changes state.

This works because misunderstanding is cheapest before implementation. A plan exposes wrong assumptions, missing constraints, unnecessary rewrites, and accidental scope expansion while they are still words. Once the agent has produced a large diff, review shifts from steering to archaeology: reconstructing why each change exists, which intent it served, and whether the whole branch is pointed at the right problem.

The misconception is that planning is only for large changes. Size is the wrong signal; ambiguity is the signal. A tiny pricing-rule edit, permission check, migration, or security exception can be more plan-worthy than a broad mechanical rename. If the exact diff could be described in one sentence, planning may add little. If the request can be interpreted multiple plausible ways, the plan is where those interpretations get surfaced.

With an agent, apparent confidence is not evidence of shared understanding. The model can proceed fluently from a mistaken premise and still produce coherent code. The plan is the cheap synchronization point: it lets a human correct the goal, boundaries, or target files before momentum turns a misunderstanding into a review burden.

Install it

npx klay practices add plan-before-apply

AGENTS.mdappend-block

## Plan before you apply

- Before editing anything, state the plan: what you will change, in which files, and why.
- Wait for the plan to be accepted before writing code, unless the task is a one-line fix.
- If the task is ambiguous, say which reading you chose and what you would have done otherwise.
- If the plan changes while you work, say so before continuing rather than after.

The previews are the first lines of each file; the command writes them in full. Existing files are never overwritten.

How you know it stuck

This one has no automated check. You cannot statically detect whether a person read something or thought about it, and a proxy for that would be worse than saying so.

Where this comes from

Choose a permission mode - Claude Code DocsClaude Code Docs · Official docsDocuments an enforced approval gate where research and proposal happen before edits are allowed.
Best practices for Claude Code - Claude Code DocsClaude Code Docs · Official docsGives vendor workflow guidance for exploring, planning, then coding to avoid solving the wrong problem.
Research, plan, and iterate on code changes with Copilot cloud agent - GitHub DocsGitHub Docs · Official docsShows comparable first-party guidance from another major coding-agent product.
Building Effective AI AgentsAnthropic Engineering · Official docsPlaces planning and human return inside Anthropic’s reference agent loop.
Vibe engineeringSimon Willison · Named authorityAdds practitioner framing for why plan iteration is higher leverage with agents.

Questions

Does this not just slow everything down?: It front-loads the reading you were going to do anyway. The plan replaces a first pass over the diff; it does not add one.
What if the plan is wrong but the code is right?: Then you have learned the agent is guessing, which is worth knowing before it guesses about something you cannot check as easily.