Read-only first: planning sessions before an agent edits code

Read-only first: planning sessions before an agent edits code means every non-trivial change starts with a session that can read the repository but cannot change it, and that session ends with a written, scoped task that a later write session carries out. In Claude Code the read-only phase is plan mode; in Codex CLI it is the read-only sandbox. Both let the agent open files, search and reason about an approach while leaving the working tree untouched. The point is not caution for its own sake. A plan is far quicker to review than a diff, a wrong assumption is easier to catch before it becomes forty edited lines, and the plan gives you a natural place to say no or narrow the work. This article covers when to use a planning pass, what to ask for, and how to turn the answer into a task. Reviewing work that is already finished is a different job, covered in using an agent as a reviewer.

Why separate reading from writing

An agent that is allowed to edit tends to commit to its first plausible approach and then patch around problems as they appear. By the time you see the result, a wrong assumption is buried under the fixes for it. Separating the phases changes the order of decisions: the agent proposes, you choose, then it builds.

It also changes what you review. A plan of ten lines naming files, functions and risks can be read in two minutes. If it says it will change the shared date parser to fix one report, you can stop that before it happens rather than discovering it in a diff of thirty files.

A planning pass is worth it when the task touches shared code, when you do not know the area well, when the task text is vague, or when the change is hard to undo, such as a schema migration. It is overkill for a typo fix or a change whose diff you could predict line by line. Use judgment, but default to planning for anything you would hesitate to merge unread.

What to ask for in the planning session

Start the session read-only: plan mode in Claude Code, or the read-only sandbox in Codex CLI. Then ask for a plan in a fixed shape, so plans are comparable across tasks and agents.

Ask for the relevant files with paths and one line on why each matters. Ask for the current behavior, described from the code rather than from the task text. Ask for the proposed change file by file, with new or changed function signatures but no full implementations. Ask for the callers of anything it plans to change, found by searching the repository. Ask for risks and for the things it does not know. Ask for the check that would prove the change works, and whether that check fails today. Finally, ask for its open questions.

The question about callers is the one people skip and the one that matters most. A plan that changes a shared helper without listing who imports it has not looked yet. The question about what it does not know is the second most useful: agents rarely volunteer uncertainty unless asked.

Turning the plan into a scoped task

The output of the planning session is not permission to proceed. It is raw material for a task. Rewrite it into the shape described in how to write a task an agent can finish: one outcome, a scope taken from the plan's file list, an explicit out-of-scope list, dependencies including the callers it found, completion criteria and the check.

Then compare the plan with what you know. Search for callers of anything shared yourself. Check that the out-of-scope list covers nearby modules the plan did not mention. If the plan surfaced a decision, such as whether to keep an old function for compatibility, make the decision now and write it into the task in one line, so the write session does not make it for you.

If the plan is wrong in a basic way, do not argue it into shape in the same session. Correct the task text and run a fresh planning pass. Plans that need several rounds of correction usually mean the task was too big, and the fix is to split it. The blast radius of a change is a useful lens here.

Starting the write session

You have two options. Continue in the same session, letting the agent leave plan mode or relaunching Codex with workspace write access, or start a fresh session that receives only the finished task text. Continuing keeps the agent's understanding of the code. A fresh session is cleaner: it works from the written task rather than from a conversation in which you may have half-agreed to things you later dropped. For anything shared or risky, prefer the fresh session.

Either way, use the plan as the review baseline. When the write session ends, compare the diff with the plan's file list. A file outside the plan is not automatically wrong, but it is the first thing to ask about, and a pattern of it is covered in agents changing files you did not ask about. Then run the check you agreed on, not one the agent picks afterwards.

Keep the plan with the task record. When the work is reviewed or revisited months later, the plan explains what was intended, which a diff alone cannot.

QUESTIONS

What is plan mode in Claude Code?

Plan mode is a Claude Code mode in which the agent reads files, searches the code and proposes an approach without editing anything. You review the plan and then decide whether to let it proceed. It is useful for unfamiliar code, shared modules and changes that are hard to undo. It is an operating mode for the session, not a replacement for reviewing the eventual diff.

How do I make Codex CLI read files without changing them?

Run it with the read-only sandbox mode. In that mode Codex can inspect the workspace and describe a plan, but it cannot write to it. Use it for the planning pass, then start a separate session with write access once you have a scoped task. Check the sandbox and approval settings each time, since they are chosen per run.

Should the planning session and the coding session be the same agent?

Not necessarily. A fresh session that receives only the written task is often better, because it works from the agreed text rather than a long conversation. Some people plan with one tool and implement with another. What matters is that the task text, scope and completion check are fixed before any write session starts, whichever agent runs it.

RELATED GUIDES

• Cards vs scheduled tasks: what starts an agent?
• How to preview work with the BRAIN FLUID harness CLI

RELATED HARNESS PAGES

• Using an AI agent as a reviewer, not an implementer Using an AI agent as a reviewer, not an implementer: read-only review sessions, what to ask, and why findings are input rather than a verdict.
• How to write a task an AI coding agent can finish How to write a task an AI coding agent can finish: one outcome, a scope, dependencies, completion criteria and the check that proves them.
• The blast radius of AI code changes The blast radius of AI code changes: what one agent edit can break elsewhere, a worked rounding example, and how a reviewer finds affected features.
• Claude Code project management Claude Code project management as a workflow: run Claude from project cards, schedule tasks and review results before you accept them.