The most expensive thing in software isn't bugs, it's rework. The requirement says "add login." You build email + password. Turns out the client wanted phone + OTP. You rebuild. Now they want enterprise WeChat scan too. A week down the drain. The root cause isn't bad code, it's misaligned requirements, a vague idea going straight into the IDE like driving blindfolded.
A Spec is the "align before you build" buffer. But writing one by hand is painful: PMs write prose, engineers write pseudocode, nobody reads it. This pack breaks Spec writing into six steps: interview to extract requirements, draw boundaries, fill in structure, add constraints, write acceptance cases, and review. Each step has clear inputs and outputs, turning the LLM into a requirements analyst, not a fiction writer.
1. Requirements Clarification Interview
The real danger isn't the unknown, it's the "assumed known." When a stakeholder says "simple search," they might mean Elasticsearch with tokenization and ranking. This step makes the AI an interviewer that asks questions to surface hidden assumptions.
You are a senior requirements analyst. I want to build "{{one-sentence feature description}}" but I haven't thought it through.
Interview me to clarify, following these rules:
1. Ask one question at a time, wait for my answer before the next.
2. Prioritize three blind spots:
- Hidden assumptions (premises I assume true but haven't stated)
- Hard constraints (timeline / budget / tech stack / compliance)
- Success criteria (how to judge "done" after completion)
3. Don't make decisions for me, only ask and rephrase.
4. After 5-7 rounds, compile my answers into a "confirmed facts list" and flag open questions still unanswered.
Start by asking me "who does this serve and what pain does it solve."Key point: don't let the AI dump five questions at once, people will half-answer. One-by-one probing uncovers real constraints. In my own use, this step most often surfaces things like "oh, it also needs to work offline" or "this data can't leave the country", stuff nobody mentioned at kickoff.
2. User Stories and Boundaries
Requirements are clear, now write them down, and critically, write what you won't do. The most common Spec gap is documenting only the happy path, leaving edge cases to be improvised during development.
Based on the following requirement description, break it into user stories + boundary notes.
Requirement description:
{{paste the confirmed facts list or raw requirements from the previous step}}
Output format:
1. User story: As a {{role}}, I want to {{action}}, so that {{value}}
2. Happy path: numbered steps from entry to completion
3. Exception paths: list failure scenarios for each step (insufficient permission / missing data / timeout / concurrency conflict)
4. Explicit non-goals: features out of scope this iteration, with reasons (to prevent scope creep from "just add it quickly")
5. Boundary values: specific numbers for input length / max count / concurrency / timeout
Constraints: exception paths must be at least 1.5x the happy path; list at least 5 non-goals.Why force 1.5x exception paths? People naturally only think of the smooth route. Force the AI to over-produce exceptions, then you trim, easier than thinking of them all yourself. The "non-goals" column I added after getting burned: one project had scope balloon indefinitely because the client kept saying "isn't this supposed to be included?"
3. Functional Spec Structure
The interview and user stories are raw material, this step pours them into a fixed skeleton. A structured Spec gives reviewers something to check against and developers a reference.
Organize the following into a functional Spec using this structure strictly:
Source material:
{{paste user stories + boundaries}}
Structure:
## Goal
One sentence on what problem this feature solves, no implementation details.
## Target Users
Who uses it, in what scenario, how often.
## Core Flow
Numbered steps for the main flow, each step annotated with input and output.
## Interface Definition
List exposed interfaces (API / function / UI entry), each with: input params, output params, error codes.
## Data Model
Which entities, fields, relationships are involved, mark which are new vs reusing existing.
## Acceptance Criteria
Each starts with "can ___", must be test-verifiable, no subjective words like "good experience".
Constraints: each section max 8 lines; interfaces and acceptance criteria must be directly implementable by an engineer.The keys here are "acceptance criteria must be test-verifiable" and "interface definitions must be implementable". A Spec isn't prose, it's a contract. The AI tends to write goals like "improve user experience", push it to "user sees loading result within 3 seconds", something measurable.
4. Technical Constraints and Risks
The functional Spec says "what to do", technical constraints say "under what limits". This step is the most skipped and the most likely to blow up later.
Based on the following functional Spec, list technical constraints and risks.
Spec summary:
{{paste the core of the functional Spec}}
Output:
1. Performance constraints: response time / throughput / data volume, with specific metrics (not "needs to be fast")
2. Security and compliance: data storage location, PII involvement, auth method, compliance (GDPR / PIPL etc.)
3. Dependencies: which internal services / third-party APIs, their SLAs and degradation strategies
4. Migration and compatibility: historical data migration, impact on existing features, rollback plan
5. Risk register: Top 3 risks by "probability x impact", each with a mitigation measure
Constraints: each item must have a specific number or plan, no "needs attention" or "depends" filler.If you've been burned, you know the value is in "dependency SLAs" and "rollback plans". When integrating third parties, you assume they're always up, and only discover there's no fallback when they go down. Launching without a rollback plan means hard-reverting code when things break. Make the AI force these two out first.
5. Acceptance Cases
A Spec without acceptance cases is scrap paper, no matter how nice it reads. This step translates acceptance criteria into executable Given-When-Then, so devs write tests against them and QA verifies against them.
Convert the following acceptance criteria into testable acceptance cases.
Acceptance criteria:
{{paste acceptance criteria from the functional Spec}}
Each case uses Given-When-Then format:
- Given: preconditions (data state / user role / system state)
- When: trigger action (specific operation or API call)
- Then: expected result (assertable state change / return value / side effect)
Requirements:
1. Each criterion needs at least 1 positive case + 2 negative cases (bad input / no permission / boundary)
2. Then must be assertable, no "displays correctly" or "feels smooth"
3. Mark which cases can be automated and which need manual verification
Output: table with columns "Case ID | Criterion | Given | When | Then | Automatable"Given-When-Then is old-school BDD, but it works. The key is that Then must be assertable: "returns 200 and body contains orderId" is good, "page looks fine" is bad. The AI defaults to the latter, push it.
6. Review and Iterate
A finished Spec isn't the endpoint, it's the start of review. This step makes the AI switch roles to a nitpicking reviewer, hunting only for holes.
You are a strict technical reviewer. Review the following Spec, find problems only, no praise.
Full Spec:
{{paste the complete Spec}}
Checklist:
1. Ambiguity: find 2+ descriptions that can be read multiple ways, point out the ambiguity and demand clarification
2. Gaps: compare against user stories, list scenarios the Spec doesn't cover
3. Contradictions: find conflicting constraints or acceptance criteria
4. Untestable: flag acceptance criteria that can't be verified by tests
5. Over-engineering: flag "bonus implementations" beyond current scope
Output: a prioritized issue list, each tagged "must fix / should fix / optional".
End with a "ready for development" verdict: Yes / No / Conditional Yes.The soul of this prompt is "problems only, no praise". The AI defaults to compliment-then-critique, diluting real issues. Forcing it to only report problems squeezes out the substance. I consistently catch 2-3 real gaps in this step, saving rework later.
How to Use
The six steps aren't a one-way street, they're a loop:
- Round 1: Take a vague idea, run the "requirements clarification interview" for 5-7 rounds, get the facts list.
- Round 2: Feed the facts list into "user stories and boundaries", get structured stories.
- Round 3: Pour stories into "functional Spec structure", then run "technical constraints" and "acceptance cases".
- Round 4: Throw the full Spec at "review and iterate", fix per the issue list, then review again.
Both Claude and DeepSeek work. Claude's long context is great for feeding the full Spec in for review; DeepSeek is solid for structured docs and the interview probing. If you use Claude Code, pair this with the /spec skill: use these prompts for the Spec draft, then /spec to scaffold code from the Spec, keeping spec and implementation in sync.
Pitfalls
- Letting the AI invent the whole Spec: The AI doesn't know your business facts, it'll fabricate plausible-sounding fake data. You must answer the interview questions yourself, fill in domain knowledge manually, the AI only asks the right questions and formats.
- Untestable acceptance criteria: "The system should run stably" can't be verified. Push the AI to "P99 response < 500ms under 100 concurrent users".
- Confusing solution with requirement: A requirement is "what the user wants", a solution is "how to do it". A common Spec mistake is writing "use Redis cache" into the requirement, locking the implementation. Write requirements at the goal level, solutions at the technical level.
- Stopping after one review round: The first review always misses things. Run at least two rounds, the second focused on whether the first-round fixes introduced new problems.
References
- Anthropic, "Prompt engineering": docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview
- Atlassian, "Writing effective product specs": atlassian.com/agile/product-management/product-specs
- Martin Fowler, "Specification By Example": martinfowler.com/bliki/SpecificationByExample.html
- Cucumber, "BDD Introduction (Given-When-Then)": cucumber.io/docs/bdd/