Interview-Driven Specs & Codebase Q&A

Flip the direction: let Claude interview you

For a small task, a good prompt is enough. For a larger feature, the hard part isn't writing instructions — it's that you haven't made all the decisions yet. You know the goal but not the edge cases, the failure behavior, or where the scope line sits. Prompting an agent with an under-decided feature gets you an implementation of the gaps.

The fix is to reverse roles — make Claude the interviewer:

I want to build [feature X]. Interview me in detail using the
AskUserQuestion tool. Ask about requirements, edge cases, and
constraints — dig into the hard parts I might not have considered.
Then write a complete spec to SPEC.md.

Claude asks structured questions one at a time — what happens when the payment fails mid-flow? should deleted users keep their history? is this synchronous or queued? — and each question forces a decision you'd otherwise have made implicitly, mid-implementation, at the worst possible time. The output is a written spec: every decision captured in SPEC.md.

Execute the spec in a fresh session

Counterintuitive but important: don't implement in the interview session. Start a fresh one and point it at SPEC.md.

Two reasons. The interview session's context is full of meandering Q&A — half-formed ideas, rejected options — which dilutes implementation focus. And the spec is a written artifact to check against: the implementing session (and a reviewing subagent later) can verify work against SPEC.md line by line, which a conversation history can't support.

What a good spec contains

The best specs are self-contained — readable by a session with zero other context:

• Named files and interfaces — "add RateLimiter middleware in src/middleware/rateLimiter.ts", not "add rate limiting somewhere sensible."
• Explicit out-of-scope statements — "no per-user custom limits in this version." What you don't say gets guessed.
• An end-to-end verification step — how to prove the whole feature works, not just its parts.

A skeleton that covers the essentials:

# SPEC: Request rate limiting

## Goal
Reject requests over 100/minute per API key with HTTP 429.

## Files
- src/middleware/rateLimiter.ts  (new — RateLimiter middleware)
- src/app.ts                     (register the middleware)

## Decisions
- Sliding window, in-memory store; Redis is out of scope this version.
- 429 body: { error: "rate_limited", retryAfterSeconds }

## Out of scope
- Per-user custom limits; admin bypass.

## Verification
- Integration test: 101st request within a minute returns 429;
  request 1 of the next window returns 200.

The underlying principle: spec precision pays off more than watching implementation. An hour making the spec airtight beats three hours supervising an agent that's improvising around ambiguity. Front-load the decisions; the implementation becomes almost mechanical.

Codebase Q&A: the fastest onboarding tool

The same conversational ability makes Claude the best ramp-up tool for an unfamiliar codebase. Ask it what you'd ask a senior engineer — no special prompting needed:

How does logging work in this codebase?
What edge cases does CustomerOnboardingFlowImpl handle?
Why does line 333 call foo() instead of bar()?

Claude explores the code and answers with references to actual files. The compounding effect is real: at one team, a week of asking Claude architecture questions replaced most of the "quick question" interruptions that new engineers usually aim at senior teammates — the newcomer ramps faster and the seniors keep their focus.

For questions about why code is the way it is, point at the history instead of asking cold:

Look through ExecutionFactory's git history and summarize how its
API came to be.

Commit messages and diffs record intent that the current code no longer shows; directing Claude to that source gets you the story, not a plausible guess.

Feed the conversation rich inputs

Both patterns improve with better raw material. Instead of describing things, hand them over:

• @file references pull a file directly into the conversation — "@src/auth/session.ts — why do we rotate tokens here?"
• Pasted screenshots — a UI bug screenshot beats three paragraphs describing it.
• URLs to docs or issue threads (allowlist domains you use often in /permissions so each fetch doesn't need approval).
• Piped data — logs, CSVs, API responses, straight into context.

The habit that ties this lesson together: stop translating and start handing over. Don't summarize the file — reference it. Don't describe the bug — paste the screenshot. Don't guess at requirements — get interviewed until they're written down. Every translation step you skip is fidelity you keep.