Skip to content
Claude Code Guide

Phase 2: Interactive Specification

The spec isn't a document you write alone and hand off. It's a conversation between you and Claude Code where you collaboratively define what you're building and why.

Why, What, How — in that order

Most engineers jump straight to "how." The interactive specification phase forces the right sequence:

  1. Why does this need to exist? What problem are we solving?
  2. What exactly are we building? What's in scope, what's out?
  3. How will we build it? Architecture, data flow, user experience.
Try this prompt
I want to build [project description]. Before we write any code, I need you to ask me clarifying questions about:

1. Who is the target user?
2. What's the core problem they face?
3. What does success look like?
4. What are the constraints (time, budget, tech stack)?
5. What's explicitly out of scope?

Ask me these one at a time. Challenge vague answers.
This turns Claude into an interviewer. The back-and-forth surfaces assumptions you didn't know you had.

The collaborative session

This is not a one-shot prompt. It's an interactive session where:

  • Claude asks clarifying questions — forcing you to articulate implicit assumptions
  • You identify risks — what could go wrong technically, from a UX perspective, or in the market
  • Together you resolve ambiguities — "should the dashboard auto-refresh or manual?" becomes a deliberate decision, not an afterthought
  • Decision points are documented — every fork in the road gets a recorded choice and rationale

Surfacing hidden requirements

The best specs come from adversarial questioning. Ask Claude to poke holes:

Try this prompt
Here's my current spec for [project]:

[paste your spec]

Act as a skeptical senior engineer reviewing this spec. Identify:
- Unstated assumptions
- Edge cases I haven't considered
- Potential performance bottlenecks
- Security concerns
- UX friction points

Be specific. "Consider error handling" is not useful. "What happens when the API returns a 429 during the initial data load while the user is on a mobile connection?" is useful.
The more specific the critique, the more valuable. Vague feedback creates vague fixes.

Note

During the zenith.chat hackathon build, this phase caught a critical issue: we'd assumed real-time WebSocket connections would work in the demo environment, but the venue's network had strict firewall rules. We pivoted to SSE before writing a single line of WebSocket code.

Output of this phase

By the end of the interactive specification, you should have:

  • A clear problem statement and success criteria
  • Defined scope boundaries (what's in v1, what's deferred)
  • Identified risks with mitigation strategies
  • Key architectural decisions with documented rationale
  • A shared mental model between you and Claude about what you're building

This document becomes the foundation for Phase 3.

Next: Product Plan with Stories →