How to Get an AI Coding Agent to Explain Its Plan First

Ask an AI coding agent to add caching to a search endpoint, and most agents pick one caching approach, one TTL, one cache key format, and start editing immediately. You get working code. It might also be built on assumptions nobody confirmed: wrong store, wrong scope, wrong tradeoff, discovered a week later when someone asks why search results look stale. The fix isn't a smarter one-off prompt for that single request. It's a standing instruction, set once in your system prompt or agent config file, that makes an AI coding agent explain its plan and flag what's unclear before it edits a single file.

This covers the exact wording that works, a worked example of an ambiguous request next to the clarifying question it should produce, and where the instruction has to live so the agent actually follows it instead of skimming past it.

Why agents guess instead of asking

Most coding agents are optimized to finish the task in front of them. The training and the harness both reward a completed diff over a paused conversation. Asking a question feels like friction; producing code feels like progress, even when the code is aimed at the wrong target. Left to its own defaults, an agent resolves ambiguity the way a very fast, very confident intern would: pick the first reasonable reading and run with it, silently.

A human contractor in the same spot usually asks, because they know guessing wrong costs them a redo and costs you money. An agent has no equivalent instinct. It has whatever your instructions tell it to do, and if your instructions never mention pausing, it never pauses.

The instruction pattern that forces a pause

This is the wording, adapted to plain text you can drop into a system prompt, a CLAUDE.md, or any other project instruction file your tool reads on every run:

Before editing any file for a request that has more than one reasonable interpretation, do not write code yet. Output instead:
1. A one-paragraph plan describing the approach you intend to take.
2. The specific files you expect to touch.
3. Any assumption you are making that isn't stated in the request, labeled explicitly as an assumption.
4. If two or more genuinely different implementations would satisfy the request, ask one specific clarifying question instead of picking one silently.
Only start editing after the user confirms the plan or answers the question. A request counts as ambiguous if the correct implementation depends on information you don't have: which layer to change, which existing pattern in the codebase to follow, what tradeoff the user will accept, or what "done" actually means here.

Four details in that instruction are doing the real work, and each one fails quietly if you drop it.

• Naming the files it expects to touch, before touching them. This is what surfaces scope creep early: if the agent lists four files for what you thought was a one-line change, that's your signal something is off, before you've reviewed a diff.

• Labeling assumptions explicitly, rather than baking them into the diff where you'd have to reverse-engineer them from the code.

• One specific question, not a list. An agent that asks five questions per request trains you to stop reading them, which defeats the whole point. If there are several unknowns, it should ask about the one that changes the implementation the most and treat the rest as stated assumptions.

• A concrete ambiguity test: does the correct implementation depend on information the agent doesn't have. Without that test, agents either ask about everything or ask about nothing, because they have no rule for telling a real fork in the road from a trivial detail.

A worked example: the same request, two outcomes

The request

"Add caching to the search endpoint." Six words, and at least three genuinely different correct implementations hiding inside them.

Without the instruction

> Request: "Add caching to the search endpoint." > Agent (no instruction): adds a Redis client dependency, wraps GET /api/search in a 300-second cache keyed on the raw query string, commits the change, moves on. No mention that Redis wasn't already in the stack, no mention of the TTL choice, no flag that stale search results might matter to the product.

With the instruction in place

Before I start: "caching" here could mean a few different things, and the right one changes which files I touch. Plan: add response caching to GET /api/search, keyed on the normalized query plus active filters and page number, default TTL 5 minutes unless you tell me otherwise. Files I expect to touch: routes/search.ts, lib/cache.ts (new), config/env.ts. Assumptions: stale results for up to the TTL window are acceptable to the product, and there's no existing cache layer (I checked lib/ and config/, didn't find one). Question: do you want this cached in-memory, which is simplest but wrong if search runs behind more than one server process, or in Redis, which works across instances but needs a new env var and a running Redis instance? If you don't already have Redis provisioned I'd default to in-memory and file the cross-instance case as a follow-up, but this is an infrastructure decision, not just a code one, so I wanted to check first.

That plan took roughly as long to generate as the silent version took to start editing. The difference is what it prevented: shipping a Redis dependency into a team that hadn't provisioned Redis, or the opposite mistake, an in-memory cache quietly doing nothing useful on a service that already runs six instances behind a load balancer. Both are the kind of bug that doesn't show up in a quick test, only in production traffic patterns.

What belongs in the plan

Keep the plan itself short. Its job is to surface a decision, not to document the whole change. Four things, every time:

• The approach, one paragraph, plain language, no code yet.

• The exact files expected to change.

• Assumptions, stated as assumptions, not folded silently into the diff.

• One clarifying question, only when the request is genuinely ambiguous, plus a plain statement of what's explicitly out of scope for this change.

Where this instruction actually has to live

Agents deprioritize instructions buried deep in a long file, so put this near the top of whatever your tool reads first: a AGENTS.md file agents actually follow, a CLAUDE.md, a Cursor rules file, or the custom-instructions field for whichever harness you're using. If you run more than one AI coding tool across a team, put the same instruction in each tool's config rather than assuming it carries over. It doesn't.

The instruction pattern itself isn't specific to coding. The same underlying idea, prompt patterns that get any AI model to ask before answering instead of guessing, applies to chat assistants too. What's different for a coding agent is the trigger: the ambiguity test has to be about files, layers, and tradeoffs, not just missing context in a sentence.

When to skip the plan step

Don't apply this to everything. A plan step on every single request, including the ones with exactly one reasonable reading, trains people to stop reading plans and click approve on autopilot, which is worse than not having the instruction at all. Skip it for:

• Single-interpretation fixes: a typo, a rename you specified exactly, a version bump, a one-line null check where the fix is the only fix.

• Changes confined to one file where the request already states the exact behavior wanted.

• Anything you've already reviewed and approved in a previous plan step for the same piece of work.

Keep it for anything touching more than one file, anything near auth, billing, or data migrations, and anything where the request could reasonably be read two different ways. That overlaps with, but isn't the same as, the separate problem of an agent changing code nobody asked it to touch, which is about boundaries rather than interpretation; the plan step helps with both, but it's aimed specifically at ambiguity, not scope.

Checking whether it's actually working

After a week of real use, look at what fraction of requests produce a plan versus an immediate edit. If it's asking on nearly everything, the ambiguity test in your instruction is too loose; tighten the examples of what counts as ambiguous. If it never asks, the wording is being ignored, which usually means it's in the wrong file, buried under unrelated instructions, or contradicted by something else in the same config telling the agent to "just get it done." For plans the agent does produce, run them through a proper plan-review checklist before approving, blast radius, irreversible operations, secrets, and rollback are worth checking even on a plan you asked for.

Frequently asked questions

Will this slow down every request the agent handles?

No, only the ones that hit the ambiguity test. Single-interpretation requests, most day-to-day edits among them, skip straight to code. The pause only fires on requests where the implementation genuinely forks.

What if the agent asks a question but the answer barely changes the code?

That happens, and it's cheap insurance rather than wasted time. A fifteen-second exchange that confirms a low-stakes assumption is still far cheaper than a diff built on the wrong one. If it happens constantly for the same category of decision, that's a sign to add the answer as a standing default in your instructions so the agent stops asking about it.

Does this work when the agent is running unattended, with nobody to answer?

Pair it with a fallback rule for that mode specifically: when nobody can answer, take the safer or more reversible option, log the assumption in the commit message or PR description, and flag it for review rather than blocking indefinitely. Worth reading alongside guidance on how long to let an agent run unattended in the first place, since the two settings interact: longer unattended runs need a clearer default-assumption rule, not a looser ambiguity test.

Can the agent ask more than one clarifying question if there are several unknowns?

Better to avoid it. Bundle related unknowns into a single question with options, or resolve the smaller ones yourself as stated assumptions and reserve the actual question for the one decision that changes the implementation the most. A wall of five questions gets skimmed and answered carelessly, which produces the same wrong outcome as not asking at all.

Does the exact wording of the instruction matter, or will any version work?

The specific parts matter more than the exact sentences: naming files before touching them, labeling assumptions instead of hiding them, capping it at one question, and giving a concrete test for what counts as ambiguous. Paraphrase freely, but keep those four elements, and keep the instruction near the top of whatever file your agent reads first.