Specification Mastery
What Belongs in Every Specification Document
The universal anatomy of a strong specification — the sections every good spec shares regardless of type.
The Universal Spec Anatomy
Whether you're writing a business plan, a design spec, or a technical feature document, strong specifications share a common structure. Learning this structure makes your Claude prompts dramatically more effective because you know exactly what to ask for.
The 8 Universal Sections
1. Purpose and Scope
Every specification must answer: "What is this document for and what does it cover?"
Purpose: [1–2 sentences on what this document enables]
Scope: [What is included]
Out of scope: [Explicitly what this document does NOT cover]The "out of scope" section is as important as the scope. It prevents scope creep and resolves disputes about what the document should address.
Claude prompt:
Write the Purpose and Scope section for a specification that covers [topic].
Be specific about what the spec includes and explicitly list 5 things that
are out of scope.---
2. Stakeholders and Audiences
Who uses this document and what decisions does it enable for each group?
Primary audience: [who reads and acts on this]
Secondary audiences: [who may reference it]
Decision makers: [who approves or executes based on it]Claude prompt:
For a [document type] for [product/feature], identify all stakeholders,
their relationship to the document, and what decisions they need to make
using it.---
3. Assumptions and Constraints
What must be true for this spec to be valid? What limits what's possible?
Assumptions:
- [Assumption 1] — why this is assumed
- [Assumption 2] — what happens if it's wrong
Constraints:
- Technical: [e.g., must work within existing infrastructure]
- Budget: [e.g., no additional paid services]
- Timeline: [e.g., must ship before Q3]
- Compliance: [e.g., must be GDPR-compliant]This section is often skipped and then bites teams when an assumption proves false. Make it explicit upfront.
---
4. Requirements
The core of any spec. Requirements must be:
- Specific — no ambiguity about what's required
- Measurable — the reader can verify whether the requirement is met
- Necessary — if you removed it, the spec would be incomplete
- Prioritized — must-have vs. nice-to-have is clearly marked
Claude prompt:
Generate a requirements section for [feature/document].
Separate into: Must-Have (P0), Should-Have (P1), and Nice-to-Have (P2).
For each requirement, write it as a testable statement starting with
"The system must..." or "The document must..."---
5. Open Questions and Decisions Pending
Every spec has things that aren't decided yet. Documenting them explicitly is better than pretending they don't exist.
Open Questions:
- [ ] [Question 1] — Owner: [Name] — Due: [Date]
- [ ] [Question 2] — Owner: [Name] — Due: [Date]
Decisions Made:
- [Decision 1] — Made on: [Date] — By: [Name]
- [Decision 2] — Made on: [Date] — By: [Name]Claude prompt:
Review the following specification draft and identify all open questions —
places where a decision hasn't been made or where two interpretations
are possible. Format as a numbered list with a suggested decision owner
for each.---
6. Success Criteria and Acceptance Criteria
How will you know this spec was executed successfully?
Success criteria: [What measurable outcome proves this worked]
Acceptance criteria: [Specific conditions that must be true for sign-off]For technical specs, acceptance criteria map to QA test cases. For business specs, they map to business outcomes.
---
7. Risks and Mitigations
What could go wrong, and what's the plan?
Risk: [Description of what could go wrong]
Likelihood: High / Medium / Low
Impact: High / Medium / Low
Mitigation: [What reduces the likelihood or impact]
Contingency: [What you do if the risk materializes]Claude prompt:
For the following spec, identify the top 5 risks. For each, assess likelihood
and impact, suggest a mitigation, and define a contingency plan if the
risk materializes.---
8. Version History and Approvals
Specs change. Track who changed what and who signed off.
Version | Date | Author | Changes
1.0 | [Date] | [Name] | Initial draft
1.1 | [Date] | [Name] | Added risk section, revised scope
Approvals:
- [Name], [Role]: Approved [Date]
- [Name], [Role]: PendingPutting It Together: The Spec Review Prompt
Once you have a draft, use this prompt to QA it:
Review this specification document and identify:
1. Sections that are missing
2. Requirements that are ambiguous or untestable
3. Assumptions that are unstated
4. Open questions that should be answered before work begins
5. Risks that haven't been addressed
Format your review as a numbered list of specific, actionable improvements.Key Takeaways
- All strong specs share 8 universal sections regardless of document type
- "Out of scope" is as important as scope — make it explicit
- Open questions must be documented, not ignored
- The spec review prompt is your final QA pass before sending a spec to a stakeholder
---
Try It Yourself: Take a specification document you've written (or find one online). Paste it into Claude with the prompt: "Review this spec against the following 8 required sections: Purpose & Scope, Stakeholders, Assumptions & Constraints, Requirements, Open Questions, Success Criteria, Risks, Version History. For each section, identify if it's present, complete, and clear. List all gaps."