Let the agent interview you, then write the spec, then start fresh

Big features fail in a predictable way when you hand them to an agent in one prompt. The agent fills every gap in your description with a guess, builds confidently on the guesses, and you find out about the wrong ones at review. A better move is to make it ask first.

Anthropic’s Claude Code best-practices guide describes a workflow for this, and it works in any agent that can ask questions and write a file.

Step 1: have it interview you

Start with a deliberately short prompt and ask the agent to question you. The guide’s version tells Claude to use the AskUserQuestion tool and to probe the hard parts: technical implementation, UI and UX, edge cases, concerns and tradeoffs. Skip the obvious questions, and keep going until everything’s covered.

Here’s our own wording of the same idea:

I want to add CSV export to the reports page. Before writing any code,
interview me. Ask about data volume, permissions, formatting, failure
cases and anything else I haven't considered. Skip questions you can
answer by reading the code. Keep going until you have what you need,
then write a complete spec to SPEC.md.

The useful part is the questions you didn’t think of. Does the export run for ten rows or ten million? Is it synchronous? Who’s allowed to download it? Those are the gaps an agent would otherwise fill silently.

Step 2: make the spec self-contained

The guide says the most useful specs name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works. A skeleton that does that:

# CSV export for reports

## Goal
Users with the `reports:read` permission can download the current report as CSV.

## Files and interfaces
- Add `GET /api/reports/:id/export.csv` in `src/api/reports.ts`
- Reuse `buildReportRows()` in `src/reports/rows.ts`; don't duplicate it

## Out of scope
- Excel format, scheduled exports, emailing the file

## Decisions made in interview
- Stream rows, don't build the file in memory
- Cap at 100,000 rows and return 413 beyond that

## Done when
- Unit tests cover permission denied, empty report and the row cap
- Running `pnpm test:e2e reports-export` downloads a file that opens cleanly

Time spent making a spec precise pays off more than time spent watching the implementation, which is the guide’s argument too.

Step 3: start a new session

Once the spec exists, start a fresh session to execute it. The interview filled the old context with exploration and back-and-forth. A clean session has a window focused entirely on implementation, plus a written spec to refer back to. If it goes sideways, you can throw the session away without losing the thinking.

Plan mode, for the middle ground

For smaller work, Claude Code’s plan mode splits exploring from editing. Press Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan. Claude reads and answers without changing anything, then you approve the plan and it implements.

The guide is also clear about when to skip it: if you could describe the diff in one sentence, ask for the change directly. Planning is for work where the approach is uncertain, multiple files change, or you’re in unfamiliar code.

Where it falls down

Interviews cost time, and a vague answer produces a vague spec. If you reply “whatever’s sensible” to every question, you’ve handed the guessing back. Also read the spec before you execute it. An agent that interviewed you well can still misunderstand an answer, and a wrong line in SPEC.md is much cheaper to fix than a wrong implementation.

Next step: pick a feature you’d normally describe in two sentences, run the interview prompt, and count how many questions surprise you.