Planning before editing
This is the fifth post in a series on the AI engineering toolkit. The first one moved you into the terminal, the second taught the agent your conventions, the third covered the context window, and the fourth walked through the tools the agent already ships with. This post is about making the agent use those reading tools to understand the problem before it touches a single file.
The pattern is simple. You ask for a change. The agent reads enough of the codebase to know what the change involves. It writes down what it intends to do. Only after you have seen that plan does it touch a file. The rest of this post covers why that ordering matters and how each of our three usual agents lets you enforce it.
The agent edits before it understands
Hand a capable agent a task with no constraints and it tends to start writing almost immediately (just like we tend to do). It reads one file, gets a theory in its head about what the fix is, and starts patching before it has checked whether that theory survives contact with the rest of the codebase. The agent’s native toolbelt showed that it can grep the repository and trace a call chain on its own. That capability sits there unused when the agent is in a hurry to produce a diff.
The cost shows up a few turns later. The change compiles and looks plausible. Then you notice it assumed a function signature that three other call sites do not share, or it quietly duplicated a helper that already lived under a different name. Now you are reading a diff across five files, working out which parts solve the real problem and which are the agent improvising around its wrong guess, and the half-hour you spent getting here is gone whether you revert or not.
Managing context covered the other cost. When the agent makes a bad edit, reads more files to defend it, then backs out, all of that reading stays in the window. A session that takes a wrong turn early drags that junk behind it for the rest of its life, and the answers get worse as the window fills.
Read-only first
The fix is to split the work into two phases. In the first, the agent may read, search, and run commands that change nothing. It may not edit files. In the second, once you have approved what it found, it can write.
Cutting off the edit tool also shifts how the agent spends the turn. With patching off the table, the agent has nothing to do but look around, so it reads the neighboring code and the callers, and it tends to surface the awkward constraint it would otherwise have learned about by breaking something. The agent is figuring out what the code does at a point where being wrong only costs a few wasted reads.
This is why all three agents ship a dedicated mode for it instead of leaving it to the prompt. Put “make a plan before you change anything” in your instructions and it becomes one more thing the model weighs against everything else in context, easy to ignore once the agent has decided the task is simple, which is the case where you wanted the plan most. A mode that turns off the edit tool removes that judgment call from the agent altogether.
What a plan buys you
The read-only phase produces a plan, and the plan is what you review. It says which files the agent will touch and what it will do to them, written down before it does any of it. You read it in a minute. Spot a bad approach there and you fix it with a one-line reply, long before the agent has changed a dozen files on the strength of it.
A plan also surfaces disagreements you did not know you had. The agent proposes adding a field to a model. You happen to know that model gets serialized into a format you cannot touch without a migration. The agent does not know that, and the plan is where the gap shows up, while it is still a one-line fix. You add the missing context, the agent revises, and the editing starts without anyone running into the migration partway through the work.
A plan helps once the editing starts, too. It becomes part of the context the agent edits from. Once it starts changing files, it is following a description it wrote and you signed off on, so it stays closer to the agreed approach as the diff grows, which helps most on the long tasks where it would otherwise drift.
Plan mode across the three
Here the three agents are different enough to take one at a time. The idea is the same in each, and the keybindings and exact guarantees are what move around, so check the docs for whichever you use before you trust a specific flag. The details below are current as of June 2026.
Claude Code calls it plan mode, and you reach it by pressing Shift+Tab to cycle the permission modes (default, then acceptEdits, then plan), with the /plan command, or by starting the session as claude --permission-mode plan. While it is on, Claude reads files and runs exploration commands but will not edit your source. When it has a plan it presents it and asks how to proceed, so you can approve it into an editing mode, keep refining with feedback, or press Shift+Tab once more to back out without approving anything. Ctrl+G opens the proposed plan in your editor if you would rather change it by hand before Claude runs with it.
OpenCode does the same thing through two built-in agents. The default one, build, has every tool enabled. The other, plan, defaults its file-edit and bash permissions to ask, so it cannot quietly change anything. You move between them with the Tab key in the TUI: tab into Plan, describe what you want and iterate on the plan it gives back, then tab into Build and tell it to go. Since plan is just an agent defined in config, you can lock it down harder by setting those permissions to deny in your opencode.json.
Codex comes at it from its sandbox model. There is a /plan slash command that drops it into a plan mode and has it propose an execution plan before the implementation work begins. The read-only guarantee itself comes from the sandbox: run codex --sandbox read-only to let it read and analyze without touching anything, and flip sandbox modes mid-session with /permissions. Day to day the suggested setting is --sandbox workspace-write --ask-for-approval on-request, which lets Codex edit inside the workspace but ask before anything riskier. When you want pure exploration, the read-only sandbox is the tightest of the three.
The keys differ from one tool to the next. In each, the agent reads and thinks with no way to edit until you have seen its plan and let it through.
Reading and steering the plan
Treat the plan as a draft you mark up. When the agent hands you one, read it for the approach. I start with the file list, because files I did not expect usually mean the agent either found something I missed or wandered off the task, and both are worth a question before it goes any further. Then I check the ordering, since an agent will cheerfully propose editing a caller before the function it depends on even exists.
When something looks off, send it back with the specific correction before you let any of it run. A message like “the migration has to come before the model change, and leave the serialization format alone” costs you one line and the agent revises the plan. Approve the flawed plan and you pay for it later, untangling a diff that already went where you did not want it to.
Be wary of plans that are too agreeable. If you push back on a detail and the agent throws out its whole approach to match your phrasing, that is a sign it was tracking your wording more than the problem. Ask it why it chose one approach over another. If it cannot give you a reason beyond your own last message, keep prodding before you let it run.
When planning is overkill
Plan-first is my default, but I do not apply it blindly. When the change is a rename or some other edit where I already know which line moves and why, the plan costs more than it saves. Forcing a read-only phase onto a trivial edit just adds a round trip, and the agent dutifully writes a plan that says “change this line” for a task where that was never the question.
It comes down to how well you understand the change. A big change you understand cold is safe to dive into. A two-line change in code you have never read can still earn a plan, because the risk lives in the surrounding code you have not seen, and the size of the diff gives you no warning about that. My rough rule is to switch on plan mode whenever I am unsure what the change will reach, and over time you get a decent instinct for which tasks those are.
Conclusions
Make the agent understand before it edits. The trouble starts when an agent reads a single file and ships a confident guess as a diff, and the way out is to keep the edit path shut until it has explored the problem and shown you a plan you can read in a minute.
All three give you a way to do this. In Claude Code it is a plan permission mode on Shift+Tab. OpenCode ships a separate plan agent you reach with Tab. Codex leans on its read-only sandbox behind the /plan command. Keep in mind the keybindings may have changed by the time you read this, since all three move quickly.
On bigger pieces of work, or team projects, reach for spec-driven development. It is the same idea scaled up: a spec settles the scope and the definition of done before any code gets written, providing alignment to all people involved.
None of this works if you wave the plan through without reading it. The whole point is to spend a minute looking at what the agent intends while it is still cheap to redirect. The next post in the series is about reusable prompts and slash commands, so you stop retyping the same instructions every time you set one of these sessions up.