Spec-Driven Development: The Blueprint for AI Coding

When you work with a coding agent, the spec is the work. The code is just execution.

This inverts the traditional development model:

Your synthetic developer can translate requirements into code—often faster and more consistently than humans. What it cannot do is:

• Decide what the requirements should be
• Resolve ambiguity
• Ask clarifying questions

It will build whatever you specify, whether that specification makes sense or not.

The 5-Component Spec Framework

A spec that works with synthetic developers has five components. Miss any one, and you're gambling on interpretation.

1. Intent

The Question: What outcome are we trying to achieve?

Not what to build—why to build it. The agent needs to understand the purpose, not just the task.

Bad vs. Good Intent

Why Intent Matters

Intent lets the agent make reasonable choices when the spec is silent:

• Should the reset link expire? Intent suggests yes—security matters
• Should there be rate limiting? Intent suggests yes—we're reducing support load, not creating attack vectors
• Should results be paginated? Intent suggests yes—we want quick discovery, not overwhelming lists

2. Constraints

The Question: What boundaries must be respected?

Every spec has explicit requirements and implicit assumptions. Make them all explicit.

Types of Constraints

Performance Constraints

- Must complete in under 3 seconds
- Cannot exceed 100MB memory usage
- Must support 1000 concurrent users

Technology Constraints

- No SMS—email only
- Must work with existing authentication service
- No new dependencies without approval

Security Constraints

- Cannot store plaintext passwords under any circumstances
- All data must be encrypted in transit
- PII must be masked in logs

Business Constraints

- Must comply with GDPR
- Cannot access customer data without consent flag
- Must support multi-tenant isolation

Include Non-Goals

Just as important as what to do is what NOT to do:

NON-GOALS:
- This is not a full account management system—only password reset
- Do not implement multi-factor authentication in this feature
- Do not refactor existing AuthService—work with current interface

3. Tests

The Question: How do we know it works?

Acceptance criteria that can be verified. The tests aren't an afterthought—they're part of the spec.

Write Tests as Verification Points

TESTS:
✓ Reset link expires after 24 hours
✓ Works on mobile browsers (iOS Safari, Android Chrome)
✓ Fails gracefully if email service is unavailable
✓ Generates audit log entry for every reset attempt
✓ Rejects requests for non-existent accounts (without revealing account existence)
✓ Rate limits to 3 requests per hour per IP
✓ Old reset links are invalidated when new one is generated

Test Categories to Cover

4. Done

The Question: What does complete look like?

Not just "code written"—the full deployment state and approval requirements.

Definition of Done Checklist

DONE WHEN:
☐ Code passes all tests (unit, integration, e2e)
☐ Deployed to staging environment
☐ QA approved
☐ Security review passed (for security-sensitive features)
☐ Documentation updated
☐ Monitoring alerts configured
☐ Rollback procedure documented
☐ Product owner sign-off

Why "Done" Prevents Scope Creep

Without a clear definition, you get:

• "It works on my machine"
• Endless refinement cycles
• Features that technically work but aren't production-ready

The agent builds until Done is achieved—not until code compiles.

5. Context

The Question: What does the agent need to know?

Existing systems, established patterns, technology constraints. The more context you provide, the less the agent has to guess.

Types of Context

System Context

EXISTING SYSTEMS:
- Uses the existing AuthService module (src/services/auth.ts)
- PostgreSQL database with existing users table (schema attached)
- Redis for session management

Technology Context

TECH STACK:
- React 18 frontend with Tailwind CSS
- Node.js backend with Express
- TypeScript throughout
- Jest for testing

Pattern Context

CONVENTIONS:
- Follow company error-handling conventions (docs/standards/errors.md)
- Use existing logging wrapper (src/utils/logger.ts)
- All API responses follow standard envelope format

Reference Context

RELATED CODE:
- Similar feature: src/features/email-verification/
- Shared utilities: src/utils/email.ts
- API patterns: src/api/README.md

The Complete Spec Template

Here's a template you can use for any feature:

# Feature: [Name]

## Intent
[Why are we building this? What outcome do we want?]

## Constraints
### Must Have
- [Requirement 1]
- [Requirement 2]

### Must Not
- [Non-goal 1]
- [Non-goal 2]

### Performance
- [Performance requirement]

### Security
- [Security requirement]

## Tests
### Happy Path
- [ ] [Test 1]
- [ ] [Test 2]

### Edge Cases
- [ ] [Test 3]
- [ ] [Test 4]

### Error Handling
- [ ] [Test 5]

## Done
- [ ] Code complete and passing tests
- [ ] Deployed to staging
- [ ] QA approved
- [ ] Documentation updated
- [ ] Monitoring configured

## Context
### Existing Systems
[What does this integrate with?]

### Tech Stack
[What technologies should be used?]

### Patterns
[What conventions should be followed?]

### Reference Code
[What existing code is relevant?]

Example: Complete Spec

# Feature: Password Reset

## Intent
Enable users to recover account access when they forget their 
password, reducing support tickets and improving security posture.

## Constraints
### Must Have
- Email-based reset flow
- Secure token generation
- Link expiration

### Must Not
- No SMS support (out of scope)
- Do not modify existing AuthService interface
- Do not store plaintext passwords

### Performance
- Reset email sent within 5 seconds of request
- Password update completes in under 2 seconds

### Security
- Tokens must be cryptographically random (256-bit)
- Rate limit: 3 requests per hour per email
- Do not reveal whether account exists

## Tests
### Happy Path
- [ ] User requests reset, receives email within 5 seconds
- [ ] User clicks link, can set new password
- [ ] User can log in with new password

### Edge Cases
- [ ] Expired link shows friendly error
- [ ] Invalid token shows generic error
- [ ] Multiple requests invalidate previous links

### Error Handling
- [ ] Email service failure queues for retry
- [ ] Database timeout returns 503 with retry-after

### Security
- [ ] SQL injection in email field blocked
- [ ] Rate limit enforced per IP and per email
- [ ] Token not logged or exposed in URLs after use

## Done
- [ ] All tests passing
- [ ] Deployed to staging
- [ ] Security team approved
- [ ] Docs updated: docs/features/password-reset.md
- [ ] Alerts configured for email failures

## Context
### Existing Systems
- AuthService: src/services/auth.ts
- Users table: see schema in docs/db/users.sql
- Email service: src/services/email.ts

### Tech Stack
- React 18 + Tailwind CSS (frontend)
- Node.js + Express (backend)
- PostgreSQL (database)
- Jest (testing)

### Patterns
- Error handling: docs/standards/errors.md
- API responses: docs/standards/api-envelope.md

### Reference Code
- Email verification: src/features/email-verification/
- Token utilities: src/utils/tokens.ts

Key Takeaways

• The spec is the work—implementation is automated
• Five components: Intent, Constraints, Tests, Done, Context
• Intent lets the agent make reasonable choices when silent
• Constraints include non-goals—what NOT to build
• Tests are part of the spec, not an afterthought
• Done prevents "works on my machine" syndrome
• Context reduces guessing—more context = better code

This framework is from Chapter 3 of Scaling Digital Capital: The Architect's Blueprint by Chris Tansey. Get the full blueprint for building AI-augmented organizations.