Plan Mode vs. Act Mode: Let the Agent Think When the Cost of Being Wrong Is High

Use plan mode when you can’t yet describe the safe diff; let the agent act when you can. The useful distinction isn’t “big task versus small task”—it’s whether a wrong first edit creates review debt, breaks a contract, or sends the agent exploring the wrong part of the repository.

Treat planning as a read-only reconnaissance pass with a deliverable, not as the agent narrating its thoughts before it starts changing files. A good plan gives you enough evidence to approve an implementation. A bad one is a polished to-do list that could apply to any repository.

Plan first when the repository can surprise you

Start in plan mode for a dependency upgrade, auth or permission change, schema migration, framework replacement, concurrency bug, or anything that crosses a package boundary. Those tasks have hidden decisions: compatibility policy, rollout path, ownership boundaries, generated code, deployment order, and what “done” means beyond a green unit test.

Give planning a short budget. Two minutes of read-only investigation is cheap if it prevents a 45-minute agent run from editing eight packages and discovering at the end that the API was intentionally frozen. If the plan cannot name the existing behavior, the likely edit locations, and the command that proves the result, don’t approve it yet.

This is especially valuable in a codebase you don’t know. The agent can search faster than you can, but it can also confidently follow the first plausible abstraction it finds. A planning pass makes that choice visible before it becomes a diff.

Make the plan earn approval

Ask for a plan with concrete outputs. Don’t ask “what would you do?” Ask the agent to inspect first, make no edits, and return the proposed change in a format you can challenge.

1. Current behavior: name the entry point, relevant call path, and the test or production behavior that establishes the baseline.
2. Scope: list the files expected to change and why; call out files deliberately left alone.
3. Design decision: state the chosen approach, one rejected alternative, and any compatibility or rollout consequence.
4. Validation: give the exact commands to run, plus one behavioral check that would fail with the old implementation.
5. Open questions: stop and ask these before implementation rather than choosing defaults silently.

Here’s a prompt worth saving as an agent command or project instruction: “Inspect only. Do not edit files, run migrations, install dependencies, or call external services. Return current behavior, proposed file-level changes, risks, non-goals, exact validation commands, and questions that require my decision. If evidence is missing, say what you searched and stop.”

The prohibitions matter. “Plan” is not always an enforceable safety boundary. A tool may still be able to run shell commands, inspect external systems through MCP, or create worktrees depending on its configuration. Define the allowed tools, not just the desired tone of the answer.

Use the control your tool actually provides

Claude Code exposes a real permission mode for this workflow: start it with claude --permission-mode plan. That is more reliable than merely telling an agent to be careful, because the session begins in a mode intended for planning rather than editing. Keep the plan in the same session when possible so the implementation phase inherits the repository findings instead of rediscovering them.

Codex now has a native /plan workflow in its app, CLI, and IDE extension. Use it for the first pass, review the sequence, then switch to execution only after you’ve resolved decisions the plan surfaced. For longer work, put the approved plan in a repository file such as docs/agent-plans/cache-invalidation.md; that gives the next session, reviewer, or human implementer something durable to work from.

Cursor’s split is slightly different: Ask mode is read-only exploration, while Agent mode can explore, edit multiple files, and run commands. Start in Ask when you want architecture reconnaissance or a change proposal, then move to Agent with an explicit approved scope. In the CLI, be more deliberate: Cursor documents that non-interactive -p runs have full write access, so “print a plan” is not a substitute for permissions. State “do not write code” and keep it interactive when you need a human checkpoint.

When act mode is the faster, safer choice

Don’t turn a one-file correction into a design review ritual. Go straight to action when you can already say something like: “In packages/api/src/parse.ts, preserve empty query values, add the regression case in parse.test.ts, and run pnpm test parse.” That prompt contains the scope, intended behavior, and verification target. A separate plan would mostly repeat information you already supplied.

Act mode is also appropriate for reversible, independently testable work: adding a missing test, renaming a local symbol, updating a stale import, repairing a formatting violation, or implementing a small UI adjustment with a screenshot test. Keep auto-run narrow, though. An agent that can edit a file safely does not necessarily need permission to run package installs, database commands, or browser automation.

Plans are bad at evidence they cannot obtain

Planning can create false confidence. The agent may infer a deployment topology from Terraform files it can see but miss the manual step your platform team performs. It may identify the correct code path but not know that a large customer relies on an undocumented response field. It may produce a reasonable migration order while failing to account for a backfill that exceeds your maintenance window.

So review plans for assumptions, not prose quality. Look for phrases such as “likely,” “appears,” and “should,” then either point the agent at the evidence or turn the uncertainty into an explicit question. If it cannot inspect staging, production telemetry, a ticket, or a design decision, the plan should say so.

Turn approval into a clean handoff

After you approve, give the agent a bounded execution instruction: “Implement only steps 1–3 of the approved plan. Do not expand scope. Run pnpm lint, pnpm typecheck, and pnpm test --filter api. Stop if the public response shape changes or if a migration is required.” That’s more effective than “go ahead,” because it defines both the finish line and the reasons to return control to you.

Then review the diff against the plan, not just against your intuition. If the agent touched an unplanned directory, skipped a stated validation command, or introduced a new dependency without calling it out, send it back. Plan mode has done its job when it gives you a concrete contract for that conversation—not when it makes the agent sound more thoughtful.