Claude Code misread a vague request and built the wrong thing? Make it show a design preview first. A six-point checklist, a prompt and settings.
When Claude Code builds the wrong thing from a vague request, the cheapest place to catch it is before the first edit. Make it write down what it intends to build, then read that preview against what you meant: its goal in its own words, what it will and will not touch, every assumption you did not state, the questions whose answers would change the design, and how you will check the result. A preview is quick to read. A large diff built on a misreading has to be read, understood and then unpicked.
Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section accordingly. Everything before that section works with plain Claude Code.
What building the wrong thing looks like
The code can be fine. It does what Claude understood, and Claude understood something other than what you meant. Anthropic's best-practices page lists this first among the ways a session goes differently than expected, and diagnoses it as Claude "missing information it can't get from reading the repo." The page also covers preferences: when two approaches are reasonable, "Claude can't read that from the code, so if you care which one it picks, say so up front."
Sources: Claude Code docs: Best practices
The misreading runs in both directions. The same page says Claude "tends to read a request conservatively and build the smallest thing that satisfies it, since it can't see how much you were hoping for." Anthropic's prompting guide notes a related slip: asked "can you suggest some changes," Claude "will sometimes provide suggestions rather than implementing them, even if making changes might be what you intended." And users report over-building. One GitHub issue says Claude Code "implements features based on misunderstandings rather than asking clarifying questions." Another, about a literal data conversion, says the model "added features nobody asked for."
Sources: Claude Code docs: Best practices, Anthropic prompting best practices, anthropics/claude-code issue 48030, anthropics/claude-code issue 93407
The two issues are single users' reports, not measurements, and neither gives a rate. A Hacker News commenter describes the other side: Claude Code "often asks clarifying questions when it is unsure how to implement something," and when it misreads, their remedy is to be more specific and split the work. Both experiences can be true. One plausible difference is whether the request left a decision open.
Sources: Hacker News comment by js8
What research says about agents that guess
Researchers have built benchmarks for this exact gap. Ambig-SWE is an underspecified variant of SWE-Bench Verified, and it scores three steps: noticing that an instruction is underspecified, asking targeted questions, and using the answers. Its authors report that models "struggle to distinguish between well-specified and underspecified instructions," that models default to non-interactive behavior without explicit encouragement, and that when models interacted with a simulated user, performance rose by up to 74% over the non-interactive settings, though it varied across models. In the paper's first experiment the prompt made interaction compulsory, because without that, models mostly did not interact.
Other work points the same way. ClarEval injects missing goals, missing premises and ambiguous terminology into coding tasks. Its authors say evaluations have mostly rewarded "guessing" user intent, and that in tests on eleven agents, models that excel at coding often lack the strategic communication skills efficient partnership requires. The Ask or Assume paper contrasts developers, who resolve underspecification by asking clarifying questions, with agents "largely optimized for autonomous execution," and reports that a scaffold separating the detection of underspecification from the coding closed the gap with agents given fully specified instructions for one of its two models, and narrowed it for the other.
Sources: ClarEval (arXiv 2603.00187), Ask or Assume? (arXiv 2603.26233)
Read these with care. They test agents on benchmark tasks, and none of the three papers reports testing Claude Code itself: Ambig-SWE ran the OpenHands framework with models including Claude Sonnet 4 and Claude Sonnet 3.5. They show a pattern, a tendency to proceed rather than ask, and give no rate for your sessions. Detection was not uniform: in Ambig-SWE, Claude Sonnet 4 and Claude Sonnet 3.5 were the only models its authors credit with notable accuracy (89% and 84%, each under its best of three prompts, all of which encouraged asking questions) at telling underspecified issues from well-specified ones.
Sources: Ambig-SWE (arXiv 2502.13069), ClarEval (arXiv 2603.00187), Ask or Assume? (arXiv 2603.26233)
Claude Code's defaults tilt the same way. The permission modes page says that from v2.1.283 auto mode is the built-in starting mode for interactive terminal and VS Code sessions, with exceptions the page lists. It also says auto mode "nudges Claude to keep working without stopping for clarifying questions, though Claude still asks when your prompt or a skill explicitly relies on it." The page's own caution is to use auto mode for "tasks where you trust the general direction." Its classifier is described as reviewing actions before they run and blocking anything that "escalates beyond your request." That is a guard on actions. The page does not describe it as a way to confirm that Claude understood a vague request correctly.
Sources: Claude Code docs: Permission modes
None of this means Claude Code never asks. The docs show it does when you tell it to: for a feature you have not thought through, they suggest a prompt like "Interview me until you could write the spec, then write it to SPEC.md," and say Claude comes back with multiple-choice questions about the parts you have not pinned down. The built-in AskUserQuestion tool is described as one that asks multiple-choice questions "to gather requirements or clarify ambiguity." For how to write the spec itself, see How to Write a Spec an AI Coding Agent Can Follow.
Sources: Claude Code docs: Best practices, Claude Code docs: Tools reference
What silent defaults look like: three runs
To see the mechanism, one small Express app (two routes, an in-memory user store, no auth, no tests) received three prompts in headless runs on Claude Code 2.1.284 with Claude Opus 5.5, started with --setting-sources project so user settings and installed plugins stayed out. Two runs got the bare request: "Add rate limiting to the API." The third got the same request plus the preview prompt given later in this post.
| Decision | Bare prompt, run 1 | Bare prompt, run 2 | Preview prompt |
|---|---|---|---|
| Who gets limited | Each IP, counted in memory | Each IP, counted in memory | Each IP, counted in memory (listed as an assumption) |
| New dependency | No, hand-written limiter in a new file | No, hand-written limiter inside app.js | Proposed express-rate-limit, and asked whether a dependency is acceptable |
| General limit | 100 per minute | 100 per minute | About 100 per 15 minutes (proposed) |
| Signup limit | 5 per 15 minutes | 5 per hour | About 5 per hour (proposed) |
| Questions put to you before code | None | None | Six |
| Files changed | app.js edited, one file added | app.js edited | None |
Three samples from one tiny app say nothing about how often this happens. They do show how: whatever the request leaves open gets decided by the sample you draw. The window lengths differ across the runs, and both bare runs settled the dependency question without asking. Both bare replies listed their choices at the end, after the code existed. The preview put the dependency, the proxy question and the instance count in front of the reader while changing them was only a reply away. One caveat runs the other way: headless runs cannot hold a conversation, so this does not show how often an interactive session would have asked first. The bare runs had file edits auto-accepted, and the preview run attempted no edit. Two earlier trial runs, made on a different model and with a plugin loaded, are left out of the table because the setup differed.
What to look for in a design preview
A preview only helps if you read it for the right things. Six checks, applied in this order.
- The goal in its own words. Compare the nouns. A restatement that repeats your sentence proves nothing. One that says which routes, which users and what "limit" means gives you something to accept or reject.
- A change list and a not-touching list. Malte Ubl's write-up of Google's design-doc practice lists non-goals next to goals, and defines them as "things that could reasonably be goals, but are explicitly chosen not to be goals." A not-touching list does the same job at the scale of one task. Ask for both lists, then compare their size with what you expected, in both directions: more files than the request implies, or fewer features than you hoped for.
- Assumptions you did not state. The best-practices page ties wrong builds to missing information, so this is where to look. Find the decisions the code cannot answer: whom to identify, which numbers to use, whether a new dependency is acceptable, what to do on failure. Each one is a place where the agent otherwise picks for you.
- Questions that would change the design. On a vague request, a preview with no questions deserves a second look: either the request was clearer than you thought, or the gaps were filled silently. Check that each question is one whose answer changes the files or the approach.
- Reuse and patterns. Does it name the existing code it will follow and say what it will not add? Anthropic's own example prompt does this, with "follow the pattern in HotDogWidget.php" and "no new libraries." The preview prompt below does not ask for this, so add a line to it if you want it.
- A check you can run. Ask which command or screenshot will show the result, and what you should see. Anthropic's advice is to ask Claude for evidence, because "All tests pass" on its own tells you very little.
Read for what is missing, not only for what is wrong. A plan can be internally consistent and still answer a different question. One Hacker News commenter, comparing the plans two models produce for complex features, says Claude's more detailed plans "seem better if you just skim them, but when analyzed, has a lot of errors, usually." That is one person's experience with their own workflow, but it names the failure that matters here: a fluent preview approved at skimming speed. Another commenter starts a fresh session, seeds it with the plan, and tells Claude to "find ambiguities / friction points / oversights" before implementing.
Sources: Hacker News comment by patates, Hacker News comment by stingraycharles
Get the preview in plain Claude Code
Three routes. The first is advice Claude can ignore. The other two use plan mode, which blocks edits until you approve, with one exception covered below.
- Ask in the prompt. Paste the preview prompt below after any request that has more than one reasonable reading. It is text, so it is advisory.
- Use plan mode for that request. Prefix one prompt with
/plan, press Shift+Tab to cycle to it, or start withclaude --permission-mode plan. Claude researches and proposes without editing your source until you approve. At the approval prompt, "No, keep planning" keeps it in plan mode so you can say what to change, and Ctrl+G opens the plan in your editor. - Make plan mode the project default. Set
permissions.defaultModetoplanin the project's.claude/settings.json, as in{"permissions": {"defaultMode": "plan"}}. Terminal sessions started in that project honor it, which puts every session there into plan mode, so it suits a project where few tasks are one-liners. The VS Code extension does not read project settings for the starting mode, so there you setclaudeCode.initialPermissionModetoplanin your VS Code user settings instead.
Plan mode has an exception worth knowing. The permission modes page says that in interactive terminal sessions where bypass permissions are available, Claude Code does not enforce plan mode's blocks: Claude is still instructed to plan without editing, but an edit it attempts runs without prompting. Claude Code Ignores Plan Mode? What Enforces It covers that gap and what holds instead.
Sources: Claude Code docs: Permission modes
Some runs have no one to ask. The docs say a scheduled task "can't ask clarifying questions," and that dontAsk mode denies the built-in AskUserQuestion tool. In those runs, put every decision in the prompt.
Sources: Claude Code docs: Common workflows, Claude Code docs: Permission modes
Preview prompt, to paste after a request: "Before writing any code, reply with: 1. The goal in one sentence, in your own words. 2. What you will change and, separately, what you will not touch. 3. Every assumption you are making that I did not state. 4. The questions whose answers would change the design. 5. How I can check that it works. Then stop and wait for my reply." In the preview run above, Claude Code 2.1.284 answered with all five sections and changed no files. One run is an observation, not a guarantee. The docs say that whether Claude follows a line on a given turn "is still Claude's call," which is why plan mode, where edits stay blocked until you approve the plan (outside the bypass case above), is the firmer option.
If it already built the wrong thing
Rewind instead of arguing with the build in place. Run /rewind, or press Esc twice on an empty prompt, to open the rewind menu. "Restore code and conversation" reverts both, and after you restore the conversation the original prompt is put back in the input field so you can edit and resend it. Rewrite it with the missing decision stated, and ask for the preview first. Rewind has gaps: a file changed only by shell commands is not tracked, and subagent edits are usually not captured, so git remains the real backstop. What Claude Code Rewind Cannot Undo goes through the limits.
Sources: Claude Code docs: Checkpointing
When a preview is not worth it
Skip it when there is one obvious way to do the task. Ubl's guidance puts the line at ambiguity: the decision to write a design doc turns on "whether the solution to the design problem is ambiguous," and if it is not, "there is little value in going through the process of writing a doc." Claude Code's docs reach a similar place for exploring: a vague prompt like "what would you improve in this file?" is "completely fine." Use a preview when a request has several reasonable readings, touches shared interfaces, data or dependencies, or would hurt to unpick. Is Spec-Driven Development Just Waterfall? covers scaling the effort to the risk.
Sources: Design Docs at Google, by Malte Ubl, Claude Code docs: Best practices
A fair objection comes from an essay titled Plan mode is dead, by the builder of a planning-first coding app. It argues that plans as precise instructions for an agent are becoming obsolete as models get better, and that "Planning and building are interleaved and emerge more organically than plan modes allow." It keeps the other purpose of a plan, helping humans understand what is being built, as something that "matters more than ever," though it calls plan modes the wrong abstraction for that job, and says agents need to identify "the fewest places where human attention can have the greatest impact." The preview in this post aims at that last idea: it surfaces the few decisions a human has to make, and it is not a spec to write in full before every task.
Sources: Plan mode is dead, by Ayman Nadeem
Where TLM Forge fits
TLM Forge builds this pause into the workflow. It sizes each task Light, Medium or Deep. For Medium and Deep it shows you a design for your OK before building, and on Pro a hook makes subagent launches and code edits wait for your reply to the design. See design sign-off.
The limits are plain. The hook waits for a reply, and it cannot tell how closely you read the design. Light tasks get no approval step, so a misread small change goes straight to code. Setting TLMFORGE_HOOKS=0 turns the hooks off. Read each design against the checks above and ask for anything missing: TLM Forge supplies the pause, and the reading is still yours.
Frequently asked questions
01Why does Claude Code misunderstand my request?
A vague request leaves decisions open, and Claude has to fill them with something. Anthropic's docs attribute a build that differs from what you had in mind to information Claude could not get from reading the repo, such as a preference between two reasonable approaches. A written preview exposes those gaps before code exists.
02How do I make Claude Code ask clarifying questions before coding?
Ask for them. Anthropic's docs suggest telling Claude to interview you until it could write the spec, and say Claude then returns multiple-choice questions. Auto mode nudges Claude to keep working without stopping for questions unless your prompt explicitly relies on them, so make the request for questions explicit.
03Is plan mode enough to stop Claude Code building the wrong thing?
It blocks edits until you approve a plan, which gives you a chance to catch a misreading. It does not read the plan for you, and a fluent plan can rest on an assumption you never stated. Check scope and assumptions before approving. In some interactive terminal setups, plan mode's blocks are not enforced.
04How do I undo what Claude Code built when it was the wrong thing?
Run rewind, or press Esc twice on an empty prompt, and restore code and conversation to before the prompt. Then edit the restored prompt and resend it with the missing decision stated. Rewind does not track files changed only by shell commands and usually misses subagent edits, so keep git as the backstop.
05Should I preview every change before Claude Code builds it?
No. For a one-line fix with one obvious path, a preview adds overhead without much to catch. Preview when a request has several reasonable readings, touches shared interfaces, data or dependencies, or would be painful to unpick. Anthropic's docs say a vague prompt is fine when you are exploring.