You know the ritual. A feature request lands, half-formed. Before you open the agent, you open a doc. You write the context, the constraints, the edge cases you can think of, the ones you half remember from the last outage. An hour later you paste a brief that scrolls for pages into Claude Code, and the first thing it builds still misses the one decision you never thought to write down.

Anthropic's own best-practices page for Claude Code tells you to skip that ritual when you don't yet know what you want. The section is called "Brainstorm with Claude first", and it gives you the whole prompt:

I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.

The page says Claude "comes back with multiple-choice questions about the parts you haven't pinned down: per-user versus per-key limits, what happens to requests over the limit, what's out of scope. It keeps asking until the answers add up to a spec."

My take: for vague tasks, the polished upfront brief is the wrong place to spend your effort. The agent is better at finding the gaps than you are at predicting them.

Your brief only covers the gaps you can already see

A long prompt is a list of answers to questions you thought of. The trouble with a vague task is the questions you didn't think of. You can't write those answers ahead of time, however long you spend in the doc.

The same Anthropic page lists the usual ways a session goes wrong, and the first one is: "Claude built something different from what you had in mind." The cause it gives is that Claude is "missing information it can't get from reading the repo." That is exactly the information a big upfront brief tries to guess at.

An interview attacks it from the other side. The agent can read the code first. Say it finds that the auth middleware identifies callers by API key, not by user, and that there's no shared cache in the stack. Then it asks about what the code can't answer, and it asks in multiple choice, which is cheap for you to answer and hard to answer vaguely. Claude Code does this through a built-in tool called AskUserQuestion, which the tools reference describes as asking "multiple-choice questions to gather requirements or clarify ambiguity."

A developer sitting relaxed in a chair while a terminal-shaped interviewer holds up three multiple-choice cards, one card highlighted in orange
The interview flips the work: the agent finds the open questions, you only pick answers.

You still do the thinking. You just do it in response to sharp questions instead of a blank page. Picking "per key, with a 429 and a Retry-After header" from a list takes seconds. Remembering on your own to decide that takes luck.

The prompt for Claude Code, and the step people skip

The docs' prompt works as written. I'd add a little structure so the spec comes out in a shape you can check later:

I want to add rate limiting to the public API but haven't thought it through yet. Read the relevant code first. Interview me until you could write the spec. Ask in rounds of multiple-choice questions, most important first. Then write SPEC.md with: goal, out of scope, decisions, edge cases, and a "done when" line with a command to run.

The "done when" line matters because of what the same page says next. Once SPEC.md exists, "start a fresh session to build from it, so the build begins with a clean context and a written definition of done."

That's the step people skip. The interview session is full of options you rejected. A fresh session only sees what you decided.

The spec pays off a third time at review. The page suggests a prompt like this, so the reviewer checks the work against your decisions rather than hunting for bugs in general:

use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style

One interview, three uses: the questions you'd have missed, a clean build context, and a yardstick for review.

Codex has the same idea built in

This isn't an Anthropic quirk. OpenAI's Codex best-practices guide gives the same advice for rough ideas: "ask Codex to question you first," and "tell it to challenge your assumptions and turn the fuzzy idea into something concrete before writing code."

Codex also has a mode for it. The guide says Plan mode "lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation," and that you toggle it with /plan or Shift+Tab. Switch Plan mode on, then send the same request with Codex's wording:

I want to add rate limiting to the public API but haven't thought it through yet. Question me first and challenge my assumptions. When the idea is concrete, write SPEC.md with goal, out of scope, decisions, edge cases, and a "done when" line with the test command to run.

The guide also suggests a PLANS.md or execution-plan template for longer multi-step work, if you want every plan to come out in the same shape.

When the interview is a waste of time

Here's where the take stops. If you already know exactly what you want, an interview is a slow way to type it.

The clearest case is a well-specified bug. Anthropic's page has its own example under "Write a specific prompt". Instead of "fix the login bug", it suggests: "users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it." There's nothing left to ask. The symptom, the place and the definition of done are all in one sentence.

A failing test is the strongest spec there is. The same page says to give Claude "something it can run that comes back pass or fail," and OpenAI's guide says Codex can run its own check loop "only if it knows what 'good' looks like." When the test already exists, that question is answered.

So my rule of thumb:

  • You can't yet say what "done" looks like: interview.
  • You can say it, but there are product decisions you haven't made: interview, then fresh session.
  • You can say it and you have a failing test or an exact repro: write the specific prompt and skip the questions.
  • You're exploring, not building: the page says a vague prompt like "what would you improve in this file?" is "completely fine."

Time goes to waste in two places: pages of answers nobody asked for, or round after round of questions about a one-line fix.

Prompts that ask before they act

I build Hermes IDE, so weigh this section with that in mind. Hermes runs Claude Code, Codex and other coding agents side by side, each in its own terminal and its own worktree.

Hermes IDE 2.3.4, released on October 15, added Essentials to its prompt Library: the things people ask most, "from planning a trip to reviewing a pull request." The release notes say "each one asks a few questions first, so it works from a blank start." It's the same bet as the interview prompt. A prompt that asks first doesn't need you to know everything up front.

The Hermes IDE Library home view with a "What do you want to do?" search box, intent and topic chips, and Essentials cards such as Plan a trip, Eat healthier, Make a budget and Write an email
The Hermes 2.3.4 Library home view: "What do you want to do?" search, intent and topic chips, and Essentials cards.

Essentials are broad on purpose, so plenty of them aren't about code at all. Words from your search are filled into the prompt, so "Lisbon, 5 days" is already there when you open "Plan a trip". The prompt picker (⌘J, or Ctrl+Shift+M on Windows and Linux) searches with the task you already typed, and a prompt goes into the running session or starts a new task.

For coding work, the interview prompt above is the one to keep. You can paste it straight into a Claude Code or Codex session in Hermes, because each agent runs its own interface in a real terminal, so its questions show up exactly as they would anywhere else. When the spec is written, ⌘N (Ctrl+Shift+N on Windows and Linux) starts the build as a new task on its own hermes/ branch and worktree, which is the fresh session Anthropic's page asks for.

The Hermes IDE Library after searching "plan a trip", showing the Start here prompt, chips to narrow it, matches in Start here and Specific sections, and the prompt's detail with its optional questions and Use in session and Start a task buttons
Searching "plan a trip" in the Library: the Start here prompt, its optional questions, and Use in session or Start a task.

Hermes is free to download, source-available under BSL 1.1, and runs on macOS, Windows and Linux. Download it here or read the code on GitHub. It isn't affiliated with Nous Research or its Hermes Agent. The interview prompts in this post work in any terminal without it.

Try it on the next fuzzy ticket

Next time a ticket arrives as one vague sentence, don't open a doc. Open the agent, paste the interview prompt, and answer the questions. Then read the SPEC.md it writes and check whether it caught something your brief would have missed.

Do you still write the long brief first, or have you let the agent interview you? Tell me in the comments which one built the right thing.

If this was useful

The interview prompt is one technique out of many for getting the right answer from a model without over-writing the request. The Prompt Engineering Pocket Guide covers the rest: structure, examples, output shape, and when a shorter prompt beats a longer one. It's one of 8 short books in the Pocket Guides for Developers series, on agents, RAG, prompts, observability, events, databases and system design — see the whole series.

Prompt Engineering Pocket Guide: Techniques for Getting the Most from LLMs