Spec Writing
Specifications drive the entire sprint workflow. Well-written specs lead to focused implementations; vague specs cause wasted iterations. This skill covers writing effective specs.md files that guide autonomous agents toward successful outcomes.
The specs.md File
Located at .claude/sprint/[N]/specs.md, this file is the primary input to the sprint system. It tells the architect what to build and how to test it.
Essential Structure
A complete specs.md contains:
# Sprint [N]: [Short Title]
## Goal
[1-2 sentences describing what success looks like]
## Scope
### In Scope
- [Feature or task 1]
- [Feature or task 2]
### Out of Scope
- [What NOT to do]
## Requirements
[Detailed requirements - can be minimal or extensive]
## Testing
- QA: required / optional / skip
- UI Testing: required / optional / skip
- UI Testing Mode: automated / manual
Writing Effective Goals
The goal statement shapes the entire sprint. Make it outcome-focused:
Good goals:
- "Users can register, login, and reset passwords"
- "API returns paginated product listings with filters"
- "Dashboard displays real-time metrics from backend"
Bad goals:
- "Implement authentication" (too vague)
- "Fix the bug" (which bug?)
- "Make it better" (unmeasurable)
A good goal answers: "How will we know when we're done?"
Defining Scope
In Scope
List concrete deliverables:
- Features to implement
- Endpoints to create
- UI components to build
- Tests to write
Be specific. "Add user profile page" is better than "improve user experience".
Out of Scope
Explicitly exclude work to prevent scope creep:
- Related features not in this sprint
- Refactoring not needed for the goal
- Nice-to-haves for future sprints
This prevents agents from over-engineering or adding unrequested features.
Requirements Depth
Specs can range from minimal to detailed. The architect adapts accordingly.
Minimal Spec (One-liner)
# Sprint 5: Add dark mode toggle
## Goal
Users can switch between light and dark themes.
## Testing
- UI Testing: required
- UI Testing Mode: manual
Appropriate for: Simple features, trusted architect judgment, exploratory work.
Detailed Spec
# Sprint 12: User Authentication
## Goal
Complete authentication flow with email verification.
## Scope
### In Scope
- Registration with email/password
- Login with session management
- Password reset via email
- Email verification flow
- Protected route middleware
### Out of Scope
- OAuth providers (future sprint)
- Two-factor authentication
- Account deletion
## Requirements
### Registration
- Email must be unique
- Password minimum 8 characters
- Send verification email on signup
- Users cannot login until verified
### Login
- Return JWT token on success
- Rate limit: 5 attempts per minute
- Lock account after 10 failed attempts
### Password Reset
- Token expires after 1 hour
- Invalidate token after use
- Send confirmation email after reset
## API Endpoints
| Method | Route | Purpose |
|--------|-------|---------|
| POST | /auth/register | Create account |
| POST | /auth/login | Authenticate |
| POST | /auth/verify | Verify email |
| POST | /auth/reset-request | Request reset |
| POST | /auth/reset | Reset password |
## Testing
- QA: required
- UI Testing: required
- UI Testing Mode: automated
Appropriate for: Complex features, specific requirements, team handoffs.
Testing Configuration
The Testing section controls which testing agents run.
Options
| Setting | Values | Meaning | |---------|--------|---------| | QA | required / optional / skip | API and unit tests | | UI Testing | required / optional / skip | Browser-based E2E tests | | UI Testing Mode | automated / manual | Auto-run or user-driven |
When to Use Each
QA: required
- New API endpoints
- Business logic changes
- Data validation rules
QA: skip
- Frontend-only changes
- Documentation updates
- Configuration changes
UI Testing: required
- User-facing features
- Form submissions
- Navigation flows
UI Testing Mode: manual
- Complex interactions
- Visual verification needed
- Exploratory testing
UI Testing Mode: automated
- Regression testing
- Standard CRUD flows
- Repeatable scenarios
Common Patterns
New Feature
## Goal
[What the feature does]
## Scope
### In Scope
- Backend API
- Frontend UI
- Integration tests
## Testing
- QA: required
- UI Testing: required
- UI Testing Mode: automated
Bug Fix
## Goal
Fix [specific issue description]
## Root Cause
[If known, describe the cause]
## Expected Behavior
[What should happen]
## Testing
- QA: required # Regression test
- UI Testing: optional
Refactoring
## Goal
Refactor [component] for [benefit]
## Constraints
- No behavior changes
- Maintain API compatibility
- All existing tests must pass
## Testing
- QA: required # Verify no regressions
- UI Testing: skip
Tips for Better Specs
Be Specific, Not Prescriptive
Tell the architect WHAT to build, not HOW to build it:
- Good: "Users can filter products by category and price range"
- Bad: "Use a Redux slice with useSelector for filter state"
The architect chooses implementation details.
Include Edge Cases
Mention important edge cases in requirements:
- Empty states
- Error conditions
- Boundary values
- Concurrent access
Reference Existing Patterns
If the codebase has conventions, mention them:
- "Follow the existing auth middleware pattern"
- "Use the same validation approach as user endpoints"
Keep It Maintainable
Specs should be readable by humans too:
- Use clear headings
- Keep bullet points short
- Include examples where helpful
Iteration and Updates
Specs evolve during the sprint:
- Initial: User writes complete specs.md
- Phase 1: Architect may clarify or expand
- Each iteration: Architect removes completed items
- Final: Specs reflect only documented decisions
This convergent pattern keeps context focused.
Additional Resources
The /sprint:new command creates specs.md templates interactively. See the command file for implementation details.