Technical Specification Template

Overview

Without a spec, engineers fill gaps with assumptions — and assumptions are what turn into mismatched expectations, missed edge cases, and rework discovered two sprints too late. A technical spec translates product requirements into an implementable plan before the first line of code gets written.

Copy the template below, fill the placeholders, and keep it under 10 pages. If it grows past that, split it.

When to Use

Reach for this template when:

• Starting a capability that touches multiple systems or teams
• Proposing a new service, API, or major architectural change
• Handing implementation off to another engineer or team

Skip it for single-file fixes and one-pager features — a GitHub issue is enough there. And if you only need to record a single design decision, that’s an ADR, not a spec (see ADR Template).

Template

# Technical Specification: `<Capability / System Name>`

**Status:** draft | in-review | approved | implemented
**Author:** @handle
**Last updated:** YYYY-MM-DD

## 1. Objective

One paragraph describing what this spec aims to achieve and why it matters.

## 2. Background

- Current state of the system
- What problem are we solving?
- Who are the users and stakeholders?
- Links to product requirements, user stories, or market research

## 3. Goals & Non-Goals

**Goals** (must achieve):
- [Goal 1]
- [Goal 2]

**Non-Goals** (explicitly out of scope):
- [Non-goal 1]
- [Non-goal 2]

## 4. Requirements

### Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | The system must... | P0 |
| FR-2 | The system should... | P1 |

### Non-Functional Requirements

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Latency p95 | < 200ms |
| NFR-2 | Availability | 99.9% |
| NFR-3 | Throughput | 1,000 req/s |

## 5. Design

### Architecture

- Link to C4 diagrams (Context, Container, Component)
- Link to service dependency map
- Link to ADR for major decisions

### Data Model

```sql
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
```

### API Contract

- Link to OpenAPI spec or microservice contract
- Key endpoints, request/response examples

### Sequence Diagram

```mermaid
sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: order_id
  API-->>User: 201 Created
```

## 6. Implementation Plan

| Phase | Task | Owner | ETA |
|-------|------|-------|-----|
| 1 | Schema migration | @backend | Week 1 |
| 2 | API implementation | @backend | Week 2 |
| 3 | Frontend integration | @frontend | Week 3 |
| 4 | Load testing | @qa | Week 4 |

## 7. Testing Strategy

- Unit tests: coverage target, mocking approach
- Integration tests: environments, data setup
- E2E tests: critical user flows
- Performance tests: load profile, acceptable thresholds

## 8. Rollout Plan

- Feature flags: which flag, default state
- Staging soak period: duration, success criteria
- Canary percentage: 5% → 25% → 100%
- Rollback criteria: error rate > X%, latency > Yms

## 9. Risks & Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Data migration takes longer than expected | High | Medium | Run migration in batches, test on copy of prod |
| Third-party API downtime | Medium | Low | Cache responses, implement circuit breaker |

## 10. Success Metrics

- **Adoption**: X% of users use the capability within 30 days
- **Performance**: p95 latency < target
- **Reliability**: error rate < 0.1%
- **Business**: Revenue impact, cost savings

Explanation

The spec separates what (requirements) from how (design) and when (implementation plan). Goals and non-goals stop scope creep at the door. Requirement IDs make test coverage traceable — QA maps FR-1 to test cases, not to paragraphs. The design section links out to living documents (diagrams, contracts) instead of duplicating them, so nothing goes stale in two places at once. And the rollout plan forces the production-readiness conversation before coding, not during the incident.

Example: Filled-Out Requirements Section

## 4. Requirements

### Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | The system must allow users to create, read, update, and delete orders | P0 |
| FR-2 | The system must send an email confirmation when an order is placed | P1 |
| FR-3 | The system should support bulk order import via CSV | P2 |
| FR-4 | The system must enforce role-based access control (admin, manager, user) | P0 |

### Non-Functional Requirements

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Latency p95 for order creation | < 200ms |
| NFR-2 | Availability during business hours | 99.9% |
| NFR-3 | Throughput peak | 1,000 req/s |
| NFR-4 | Data durability | 99.999999% (11 nines) |
| NFR-5 | Audit log retention | 7 years |

Example: Feature Flag Rollout Config

feature_flags:
  - name: orders_v2_api
    description: "New order processing pipeline with async validation"
    default_state: off
    rollout_strategy: percentage
    rollout_steps:
      - percentage: 5
        duration: 24h
        success_criteria:
          error_rate: < 0.5%
          p95_latency: < 200ms
      - percentage: 25
        duration: 48h
        success_criteria:
          error_rate: < 0.5%
          p95_latency: < 200ms
      - percentage: 100
        duration: indefinite
    rollback_criteria:
      error_rate: > 1%
      p95_latency: > 500ms
    target_rules:
      - attribute: user_id
        operator: in
        values: [12345, 67890]  # Internal testers first

Example: Risk Assessment Template

## 9. Risks & Mitigations

| Risk | Impact | Likelihood | Mitigation | Owner |
|------|--------|------------|------------|-------|
| Data migration takes longer than expected | High | Medium | Run migration in batches of 10k rows, test on copy of prod | @dba |
| Third-party payment API downtime | High | Low | Cache responses, implement circuit breaker, queue retries | @backend |
| Frontend performance regression | Medium | Medium | Run Lighthouse CI on every PR, block merge if score drops > 5 points | @frontend |
| Schema change locks the table | High | Low | Use online schema change tool (gh-ost, pt-online-schema-change) | @dba |
| New API contract breaks mobile clients | High | Medium | Maintain v1 compatibility shim for 90 days, ship SDK update | @mobile |

Spec Review Checklist

Before circulating the spec for approval:

• Every functional requirement has a traceable ID (FR-x)
• Every non-functional requirement has a measurable target
• Goals and non-goals are explicitly listed
• Design section links to diagrams, not inline images
• Implementation plan has owner and ETA for each phase
• Rollout plan includes feature flag config and rollback criteria
• Risk table includes impact, likelihood, and mitigation for each risk
• Success metrics are quantitative and measurable
• Spec is under 10 pages (excluding appendices)

Variants

Context	Approach	Notes
Startup	Lightweight (1-2 pages)	Focus on goals, design sketch, and rollout
Enterprise	Full template with approvals	Require sign-off from architecture review board
Open source	RFC format	Publish for community comment before implementation
Regulated industry	Add compliance section	Map requirements to HIPAA, PCI-DSS, or SOX controls
Cross-team	Add dependency timeline	Show which teams need to deliver what and when

What Works

• Keep it under 10 pages; link to detail docs instead of inlining everything.
• Give every requirement an ID — test coverage mapping breaks without it.
• Review with stakeholders before implementation starts, not during.
• Update the spec in the same PR as the code change that motivated it.
• Store specs in version control next to the code they describe.
• Include a status header (draft / in-review / approved / implemented) so nobody implements a draft by mistake.
• Link the spec in the PR description — reviewers need the “why” as much as the “what”.

Common Mistakes

• Writing the spec after implementation. That’s documentation theater, not planning — and it can’t catch the design problems a spec exists to catch.
• Implementation details in the design section. Variable names and file paths belong in the PR, not the spec.
• Skipping non-functional requirements. “Should be fast” isn’t a target; “p95 < 200ms” is.
• No rollback criteria. Deciding them mid-incident is how small rollouts become big ones.
• Treating the spec as immutable. Implementation always discovers things — the spec that doesn’t get updated becomes a liar.
• No owner per phase. Diffusion of responsibility is how week-1 phases ship in week 5.

Spec Troubleshooting

• Spec stalls in review. Too long. Cut it to the TL;DR + the sections under debate, or split it — reviewers approve 4 pages, they postpone 14.
• Spec approved, then ignored. No links from the work itself. Put the spec URL in the epic, the tickets, and every implementation PR.
• Requirements drift without anyone noticing. Missing status header or stale spec. Update the spec in the same PR as the code change — same rule as docs.
• The spec answered everything except what prod actually hit. The risk table was cosmetic. Score risks honestly and put owners on the top ones.

See Also

• ADR Template — for single design decisions
• Microservice Contract Template — the API contract the spec links to
• System Diagram Template — for the architecture section
• Technical Documentation Strategy Guide — where specs fit in the bigger picture

Further Reading

• How to Write a Good Software Design Doc (freeCodeCamp)
• RFC 2119 — Requirement Levels — the MUST/SHOULD/MAY vocabulary used in requirement tables
• Google eng-practices design docs — how design docs work at scale

Companion code: the technical-spec-template companion repo has this template as a ready-to-copy .md file plus a fully filled-out example spec.