Anatomy of a Good Spec
Anatomy of a Good Spec
Your spec is your most important deliverable
In Specs Driven Development, the specification is your most important deliverable. A well-written spec is not just documentation — it is the prompt that drives your AI agent to generate the right code. The quality of your spec directly determines the quality of the generated output.
Format
Specs default to Markdown because it is readable in IDEs, renders beautifully on GitHub, and both humans and AI agents parse it effortlessly.
The requirements.md Structure
Project Overview
Start with a clear, concise description of what you are building. Include the problem being solved, target users, and the core value proposition.
Tech Stack
Explicitly list every technology, framework, and version. AI agents need precise context — do not let them guess or default to outdated versions.
Feature Requirements
Break features into user stories with clear acceptance criteria. Each story should be independently implementable and testable.
Non-Functional Requirements
Performance targets, security constraints, scalability expectations, accessibility standards. These are often more important than features.
Constraints and Boundaries
What the system should NOT do. Explicit exclusions prevent AI from over-engineering or adding unwanted features.
Writing Effective User Stories
As a [role], I want to [action], So that [benefit]. Acceptance Criteria: - Given [context], when [action], then [result] - Given [context], when [action], then [result] - Edge case: [scenario] should [behavior]
The Acceptance Criteria Rule
If you cannot write acceptance criteria for a feature, you do not understand it well enough to spec it. Go back and clarify the requirements before asking AI to implement.
Common Spec Mistakes
Too Vague
Saying 'add authentication' without specifying OAuth providers, session management, or token expiration leaves AI to make critical decisions for you.
Too Detailed
Specifying exact CSS pixel values or database column names in the spec couples it to implementation. Focus on WHAT, not HOW.
Missing Edge Cases
Not mentioning error states, empty states, or concurrent access leads to code that only works on the happy path.
No Constraints
Without explicit constraints, AI will add features you did not ask for. Boundaries are as important as requirements.
Spec Quality Checklist
Remember
A 30-minute investment in writing a good spec saves hours of debugging and rework. The spec is your leverage — it multiplies the effectiveness of every AI interaction that follows.
There are no comments for now.