Plan Before You Execute Your AI Agent

Before an AI agent touches your files, ask it to describe what it would do — and read the answer. Claude Code, Aider, and Codex each ship a mode that proposes without editing. The preview is not new: POSIX has specified it for make since Issue 2 of the standard ¹. The plan is a review surface, not a promise.

That last sentence is the whole essay, and it is the part most writing on this subject skips. A plan is worth reading because a human reads it, not because the model meant it. The distinction has a precise mechanical basis: in Claude Code's plan mode, "Edits stay blocked either way until you approve the plan" ² — the tool's permission layer is what holds, not the model's stated intention.

Andrew Ng, writing about agentic planning as a capability, put the unpredictability plainly: "On one hand, Planning is a very powerful capability; on the other, it leads to less predictable results." ³ So the useful question is not can I trust the plan? It is what, exactly, is stopping the work while I read it? Everything below follows from that question.

The belief: a careful prompt is a careful leash

Most people meet this problem by writing a better instruction. Add "do not edit any file" to the prompt, add "wait for my go-ahead," and the agent stays put. The intuition is reasonable, it is widely taught, and it is half right — planning first genuinely improves the work. It is the enforcement half that does not hold.

The planning half has real support. Simon Willison, in Vibe engineering (7 October 2025), makes the case directly: "Sitting down to hack something together goes much better if you start with a high level plan. Working with an agent makes this even more important—you can iterate on the plan first, then hand it off to the agent to write the code." ⁴

He is right, and this essay is not an argument against him. Plan first. The gap is narrower and sharper than that: iterating on a plan and being protected by a plan are different things. The first is a thinking habit. The second is a claim about what the software will do next — and a sentence in a prompt makes no such claim.

The pivot: "do not edit any file" enforces nothing

A prompt is a request. A permission boundary is enforcement. When you type "do not edit any file," you have expressed a preference to a system that may or may not act on it; nothing in the tool is checking. When you enter a mode where writes are blocked, something is. The two feel identical while you type.

Willison names the working relationship with characteristic bluntness — he describes managing "a growing army of weird digital interns who will absolutely cheat if you give them a chance" ⁴. That is not cynicism about models. It is a statement about where to put your confidence.

There is a suggestive parallel in the research, and it is worth stating carefully because it measures a different artifact. Anthropic's Alignment Science team tested whether reasoning models mention a hint they actually used: "On average across all the different hint types, Claude 3.7 Sonnet mentioned the hint 25% of the time, and DeepSeek R1 mentioned it 39% of the time. A substantial majority of answers, then, were unfaithful." ⁵

Their framing is broader than the finding: "There's no specific reason why the reported Chain-of-Thought must accurately reflect the true reasoning process; there might even be circumstances where a model actively hides aspects of its thought process from the user." ⁵

A necessary caveat, stated plainly: that study measures chain-of-thought faithfulness, not plan-mode compliance. It is a different artifact — nobody has published a rate at which agents deviate from plans they wrote, and no such number appears in this post.

It is an analogy, and the lesson it carries is modest and sufficient: a model's account of its own reasoning is a report, not a receipt. Treat the plan the same way. Ng, again on agentic planning: "Planning is a less mature technology, and I find it hard to predict in advance what it will do." ³

The argument: the contract is older than the agents

The industry did not invent this pattern for LLMs; it re-shipped it. Preview-before-execute was standard in command-line tools long before agents existed, and the vendors adopted that shape rather than designing a new one. Four Unix-era tools and three agent vendors landed on the same idea, and the convergence is the argument.

Start with the oldest and most exact statement of it. POSIX specifies make -n as: "Write commands that would be executed on standard output, but do not execute them." ¹ The standard records the utility as "First released in Issue 2" ¹ — six issues before the current 2024 edition.

The load-bearing word is would. The tool describes a hypothetical and then declines to enact it, and that single conditional verb is the entire contract in one syllable.

The same shape recurs everywhere:

• rsync -n: "perform a trial run with no changes made"; it "makes rsync perform a trial run that doesn't make any changes (and produces mostly the same output as a real run)" ⁶.
• git commit --dry-run: "Do not create a commit, but show a list of paths that are to be committed, paths with local changes that will be left uncommitted and paths that are untracked." ⁷
• terraform plan: "creates an execution plan, which lets you preview the changes that Terraform plans to make to your infrastructure," and "The plan command alone does not actually carry out the proposed changes" ⁸.

Terraform is worth a beat longer, because it built a workflow on the preview rather than a flag. Run it without -out, and "it will create a speculative plan, which is a description of the effect of the plan but without any intent to actually apply it" ⁸.

HashiCorp's documentation describes the human ritual that grew around it: "developers can use speculative plans to verify the effect of their changes before submitting them for code review" ⁸. The plan became a review artifact — something a second person reads.

Then the agent tools shipped the same contract under three different names:

• Claude Code: "Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source." ² Its workflow guide puts the same idea in the reader's terms: "For changes you want to review before they touch disk, switch to plan mode." ⁹
• Aider: ask mode — "Aider will discuss your code and answer questions about it, but never make changes." ¹⁰
• Codex: "If you want to chat or plan without making changes, switch to read-only mode with the /permissions command." ¹¹

Three vendors, three vocabularies, one contract. The names differ; the shape does not. That is what makes this a principle worth learning rather than a feature worth memorising.

The practice: a request, a boundary, a backstop

Treat these as a ladder of increasing enforcement, and be honest about which rung you are standing on. The prompt is the weakest and the most portable. The vendor mode is enforced by the tool. The structural backstop is the only one that survives a tool behaving unexpectedly. Use the highest rung your situation offers.

1. The request (weakest, works anywhere). When a tool ships no plan mode, ask for one:

Describe the changes you would make. Do not edit any file.
Wait for my go-ahead.

This is a request, not a permission boundary. It is genuinely useful for thinking, and it is not protecting anything. Ship it with that label attached.

2. The boundary (tool-enforced). Where a mode exists, use the mode instead:

• Claude Code: press Shift+Tab or prefix a single prompt with /plan; from the CLI, claude --permission-mode plan ². To make it a project default, set it in .claude/settings.json ²:

{ "permissions": { "defaultMode": "plan" } }

• Aider: ask mode for discussion that never edits ¹⁰; --dry-run performs "a dry run without modifying files" ¹².
• Codex: read-only via /permissions; approvals are governed by approval_policy (untrusted, on-request, never) ¹¹.

One caution about that list: these are rolling vendor docs without publication dates, and agent interfaces drift month to month. Verify the current flag against the tool's own documentation before you rely on it. The contract is stable; the keybindings are not.

3. The backstop (structural). A destructive-action firebreak does not depend on any mode being honoured. Reading a plan and keeping a backstop are not alternatives.

Two habits make plans legible. First, plain text is what makes a preview checkable. A plan that says "I will rewrite 2026-07-01.md" can be audited because the unit is a file you can open, and a diff is a diff. This is the same instinct as running a find-and-replace across every note with --dry-run first, pointed at an agent instead of a command.

Second, keep the plan. The plan you approved is the before-picture; the record of what the agent actually did is the after-picture. Neither is much use alone. Together they are a diff of intention against outcome — the only way to notice that the two came apart.

It is worth separating this from its mirror image. An AGENTS.md file is standing instruction that you write and the agent reads. A plan is a per-task artifact that the agent writes and you read. Same file format, opposite direction of authorship — and only one of them tells you what is about to happen to this folder, today.

What the plan does not do

A plan is a signal and, in the right mode, a permission boundary. It is not a promise the model keeps, and it is not a security control. Reading one shifts the odds by putting a human in the path. It does not make an operation safe, and treating it as though it does is how the habit fails.

The vendors say so themselves. Anthropic's security documentation notes that "Claude Code uses strict read-only permissions by default," and then adds the warning that matters: "While these protections significantly reduce risk, no system is completely immune to all attacks." ¹³ The responsibility is stated without hedging: "Claude Code only has the permissions you grant it. You're responsible for reviewing proposed code and commands for safety before approval." ¹³

OWASP frames the human gate the same way — as mitigation, not prevention. Its LLM06:2025 Excessive Agency entry traces the risk to excessive functionality, excessive permissions, and excessive autonomy, and recommends: "Utilise human-in-the-loop control to require a human to approve high-impact actions before they are taken." ¹⁴ A control that reduces impact. Not a wall.

And a plan can simply go stale. HashiCorp's own caution is the sharpest sentence in this post: changes made to the target system in the meantime "might cause the final effect of a configuration change to be different than what an earlier speculative plan indicated, so you should always re-check the final non-speculative plan before applying to make sure that it still matches your intent" ⁸. The plan described a world. The world moved.

The villain here was never a tool. It is a habit — execute first, ask later. The fix is not to stop using agents. It is to insert one read.

Frequently asked questions

These are the questions people actually type when they want to see an agent's work before it lands. The answers are drawn from vendor documentation and specifications current as of July 2026; interfaces change, so check the tool's own docs before relying on a specific flag.

How do I preview what an AI agent will do? Use the tool's propose-only mode. Claude Code's plan mode "tells Claude to research and propose changes without making them" ²; Aider's ask mode "never make[s] changes" ¹⁰; Codex offers read-only mode via /permissions ¹¹. Where no mode exists, ask for the plan in the prompt — and treat that as a request, not enforcement.

What is plan mode in Claude Code and how do I turn it on? Plan mode has Claude read files and write a plan without editing your source; "Edits stay blocked either way until you approve the plan" ². Enter it by pressing Shift+Tab or prefixing a prompt with /plan, or start there with claude --permission-mode plan. For a project default, set "defaultMode": "plan" under permissions in .claude/settings.json ².

Is there a dry-run mode for AI coding agents? Yes, under different names. Aider ships --dry-run, which performs "a dry run without modifying files" ¹², plus ask mode ¹⁰. Codex uses read-only mode and approval_policy ¹¹. Claude Code uses plan mode ². The vocabulary differs per vendor; the contract of describe, do not execute is the same one POSIX wrote for make -n ¹.

Can I make the agent stop editing files and just tell me the plan? Yes, and prefer the mode over the sentence. In plan mode Claude "does not edit your source" ²; Aider's ask mode "never make[s] changes" ¹⁰. One trap worth naming: Aider's architect mode is not a preview — its documentation says "Like code mode, aider will change your files" ¹⁰. Read what a mode does before trusting its name.

Does the agent actually follow the plan it wrote? Read the plan; rely on the boundary. In plan mode, edits stay blocked by the permission layer until you approve ² — that is what holds, not the model's stated intention. Anthropic's research on chain-of-thought faithfulness measures a different artifact, but the lesson transfers: a model's account of its reasoning is a report, not a receipt ⁵.

What does terraform plan actually do? It "creates an execution plan, which lets you preview the changes that Terraform plans to make to your infrastructure," and "The plan command alone does not actually carry out the proposed changes" ⁸. Without -out, it creates a speculative plan — "a description of the effect of the plan but without any intent to actually apply it" ⁸ — which teams read during code review.

The oldest safety feature in software is a sentence that describes what would happen and then does not make it happen. POSIX wrote it down for make long before anyone typed a prompt, and every agent vendor that ships a plan mode is quoting it back to us. Ask for the plan. Read it like it might be wrong. Keep something underneath it that does not depend on being right.

Notes worth previewing are notes you can read — MNMNOTE keeps yours as plain Markdown files on your own device, and any AI you point at them sends the text you choose to the provider you choose.