Technical Specification
A tech spec answers how we'll build something — without over-prescribing implementation details that engineers should own. It bridges product requirements to engineering execution.
Step 1: Read the Requirements
Before writing, gather the inputs. A spec without requirements is guesswork.
| Source | What to pull from it |
|---|---|
| PRD | Problem, goals, functional requirements, non-functional requirements, scope boundaries |
| Job stories | User workflows, acceptance criteria, edge cases |
| Conversation | If neither exists, interview the user to establish what the system must do and for whom |
Flag anything ambiguous. A spec built on vague requirements produces vague engineering.
Step 2: Write the Spec
Use this structure. Adapt headings to the project — not every section applies every time.
# Tech Spec: [Feature / System Name]
## Overview
One paragraph. What this is, why we're building it, and what it connects to.
Link to the PRD or source requirements.
## Technical Approach
The core design decision. How this fits into the existing system.
Keep it to the architecture level — components, their responsibilities,
how they interact. Don't write pseudocode unless it clarifies a tricky algorithm.
## Data Model
New tables, fields, or schema changes. Include:
- Field name, type, constraints
- Relationships to existing models
- Migration notes (new table vs altering existing)
## API Design
Endpoints, methods, request/response shapes.
For each endpoint:
- Method + path
- Request body / params
- Response shape
- Error cases
## Edge Cases
What happens when things go wrong or get weird.
| Case | Behavior | Rationale |
|------|----------|-----------|
| User submits duplicate | Return existing record, don't create new | Prevents data bloat |
| Payload exceeds size limit | Reject with 413, log for monitoring | Protects downstream services |
## Testing Strategy
What gets tested and how.
- Unit tests: which modules, what coverage target
- Integration tests: which workflows end-to-end
- Manual QA: what can't be automated and why
## Migration Plan
Only if changing existing systems. Cover:
- Data migration steps
- Backward compatibility (can old and new coexist during rollout?)
- Rollback procedure
## Rollout Plan
How this gets to users.
- Feature flag strategy
- Phased rollout stages (internal → beta → GA)
- Monitoring and alerting during rollout
- Success/failure criteria for each stageDecision Log
Every non-obvious choice gets logged. This prevents re-litigating decisions later and helps future engineers understand why things are the way they are.
## Decisions
### D-1: [Short description of the decision]
**Options considered:**
1. Option A — [brief description]
2. Option B — [brief description]
3. Option C — [brief description]
**Decision:** Option B
**Rationale:** [Why this option wins. Reference constraints, trade-offs,
or requirements that drove the choice.]Keep decisions numbered (D-1, D-2) so they can be referenced in code comments and PR descriptions.
Quality Checks
Before delivering the spec, verify:
- Does it answer "how" without dictating unnecessary "what exactly"? The spec should constrain the architecture, not micromanage the implementation. Engineers need room to make local decisions.
- Are edge cases covered? If you only describe the happy path, the implementation will only handle the happy path.
- Is the data model complete? Missing a field or relationship here means a migration later.
- Do API contracts match the requirements? Walk each job story through the API. Does the data flow support every acceptance criterion?
- Is the testing strategy proportional? Critical paths get thorough tests. Low-risk utilities get basic coverage. Don't spec 100% coverage everywhere.
- Is the rollout reversible? If something goes wrong in production, can you roll back without data loss?
Scope Boundaries
A tech spec is not:
- A tutorial. Don't explain how frameworks work. Assume engineering competence.
- A PRD. Don't redefine what we're building. Reference the PRD and focus on how.
- A project plan. Don't include timelines or task assignments. That's a separate artifact.
When the Spec Is Done
Ship it with:
- Clear status — Draft, In Review, or Approved
- Open questions — What still needs answers before building starts
- Review ask — Who should review (engineering, security, platform) and what feedback you need