Design Document (Tech Spec) Template

Last updated:

What it is

A Design Document — also called a Tech Spec, Technical Design Document (TDD), or Engineering Design Doc — is a structured written proposal that describes how a significant piece of software will be built before work begins. It defines the problem, scopes the solution, details the technical approach, and identifies risks so that stakeholders can review and align before implementation commences.

Unlike an ADR, which captures a single decision, a Design Doc covers the full solution space for a feature, service, or system change. It typically includes the motivating business or engineering need, a high-level architecture, key interface or data model definitions, alternatives that were considered, and a plan for testing and rollout. The document is living during the design phase and is updated in response to review feedback until it is approved.

Design Docs are particularly common at larger engineering organizations (Google, Amazon, Meta, and many others have published their internal practices), but they are equally valuable in smaller teams where the cost of rework from misaligned implementations is high relative to available engineering capacity.

Why it exists

Writing a design doc forces precision before pixels are pushed. The process of articulating the approach in writing consistently surfaces ambiguities, unstated assumptions, and integration gaps that would otherwise manifest as expensive surprises mid-implementation. Engineering teams that write design docs before complex projects consistently report lower rework rates and better alignment between implementation and original intent.

Design docs also make asynchronous review possible. Instead of convening a meeting to discuss an approach, reviewers can read the doc on their own schedule, leave inline comments, and respond when they have thought through the implications. This is especially valuable for cross-team work where scheduling synchronous reviews is difficult and stakeholders span multiple time zones.

Finally, approved design docs serve as implementation contracts. When a feature is completed, the original design doc explains why the system was built the way it was — far more so than code comments or commit messages. They are invaluable artifacts for onboarding, architecture audits, and future redesigns.

When to use

  • When building a new service, system, or major feature whose implementation will span more than one sprint or involve more than two engineers.
  • When a project requires coordination across multiple teams and explicit alignment on interfaces, data contracts, or shared infrastructure is necessary before work can begin in parallel.
  • When introducing a new architectural pattern, framework, or platform component that will influence future work and whose adoption decisions require broader review.
  • When the problem is ambiguous enough that different engineers would make meaningfully different implementation choices without a shared written specification.
  • When the project carries significant risk — security, regulatory, data integrity, or high-traffic — and stakeholders need to review the approach for correctness before it is built.

When NOT to use

  • For small, well-understood features (under a week of implementation work) where the approach is unambiguous and no cross-team coordination is required — a ticket description or brief comment is sufficient.
  • As a replacement for prototyping when the key uncertainties are technical and can only be resolved by building. Write the doc after the prototype reveals the shape of the solution.
  • When the document becomes shelfware — if the team culture does not support reading and reviewing docs before implementation, a design doc adds overhead without value.
  • For purely operational changes (configuration updates, dependency upgrades) where the "design" is straightforward and risk is manageable with testing alone.

Template

# [Feature / System Name] — Design Document

**Authors:** [Name], [Name]
**Reviewers:** [Name (role)], [Name (role)]
**Status:** Draft | In Review | Approved | Implemented | Abandoned
**Created:** [YYYY-MM-DD]
**Last Updated:** [YYYY-MM-DD]
**Tracking:** [Link to epic / project ticket]

---

## Overview

[High-level summary of what is being built, why, and the proposed approach.]

---

## Background


### Current State
[Describe the existing system behavior and its limitations.]

### Problem Statement
[Articulate the specific problem or opportunity. Use data where possible:
error rates, latency numbers, user complaints, business metrics.]

### Prior Work
- [Link to related design doc or ADR if applicable]
- [Link to postmortem or incident that motivated this work]

---

## Goals

* [Goal 1 — e.g., "Reduce p99 checkout latency from 2,000ms to under 500ms"]
* [Goal 2 — e.g., "Allow the team to deploy the service independently of the monolith"]
* [Goal 3]

## Non-Goals

* [Non-goal 1 — e.g., "This project does not address the mobile checkout flow"]
* [Non-goal 2 — e.g., "Migrating existing data is out of scope for this phase"]
* [Non-goal 3]

---

## Design

### High-Level Architecture

[Architecture overview. Example: "The system consists of three components:
an ingestion API, a processing worker, and a read API. The ingestion API
receives events from clients, validates them, and enqueues them on Kafka.
Workers consume from Kafka, apply business logic, and write results to
PostgreSQL. The read API serves queries against PostgreSQL."]

**Diagram:** [Link to Excalidraw / Miro / draw.io diagram]

### Component Details

#### [Component 1 Name]
- **Responsibility:** [What this component does]
- **Technology:** [Language, framework, hosting]
- **Key interfaces:** [APIs, queues, or data stores it owns]
- **Scaling approach:** [Horizontal / vertical / auto-scaling trigger]

#### [Component 2 Name]
- **Responsibility:** [What this component does]
- **Technology:** [Language, framework, hosting]
- **Key interfaces:** [APIs, queues, or data stores it owns]

### Data Model


```sql
-- Example: orders table
CREATE TABLE orders (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID NOT NULL REFERENCES users(id),
  status      TEXT NOT NULL CHECK (status IN ('pending','paid','shipped','cancelled')),
  total_cents INTEGER NOT NULL,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

### API Design


| Method | Path | Description |
|--------|------|-------------|
| POST   | /v1/orders | Create a new order |
| GET    | /v1/orders/{id} | Retrieve order by ID |
| PATCH  | /v1/orders/{id}/status | Update order status |

Full contract: [Link to API Contract doc]

### Key Design Decisions

1. **[Decision topic]:** [Chosen approach] — [1–2 sentence rationale]. See [ADR-NNN].
2. **[Decision topic]:** [Chosen approach] — [rationale].

---

## Alternatives Considered


### Alternative 1: [Name]
[Brief description of the approach.]

**Why rejected:** [Explain the specific limitation or trade-off that ruled it out.]

### Alternative 2: [Name]
[Brief description of the approach.]

**Why rejected:** [Explain the specific limitation or trade-off that ruled it out.]

---

## Security Considerations

* **Authentication/Authorization:** [How are callers authenticated? How is access controlled?]
* **Data sensitivity:** [What PII or sensitive data does this system handle? How is it protected?]
* **Input validation:** [How are untrusted inputs sanitized?]
* **Secrets management:** [How are credentials and API keys stored and rotated?]
* **Audit logging:** [What actions are logged for compliance or forensics?]
* **Known risks / accepted trade-offs:** [Any residual risk acknowledged by the team]

---

## Testing Strategy

* **Unit tests:** [Coverage target, key scenarios to cover]
* **Integration tests:** [Which integrations will be tested end-to-end]
* **Load / performance tests:** [Target throughput, latency SLOs, tooling]
* **Contract tests:** [If applicable — link to provider/consumer contracts]
* **Manual QA:** [Any scenarios requiring manual verification]
* **Feature flags:** [Will the feature be gated behind a flag for canary testing?]

---

## Rollout Plan

* **Phase 1 (Week N):** [What gets deployed, to which environment, with what validation criteria]
* **Phase 2 (Week N+1):** [Expand to X% of traffic / all regions / GA]
* **Rollback plan:** [How to revert if something goes wrong — feature flag off? Redeploy prior image?]
* **Monitoring:** [Which dashboards and alerts will be watched during rollout]
* **Communication:** [Who needs to be notified before / during / after the rollout]

---

## Open Questions

| # | Question | Owner | Due |
|---|----------|-------|-----|
| 1 | [Question text] | [@name] | [YYYY-MM-DD] |
| 2 | [Question text] | [@name] | [YYYY-MM-DD] |

---

## Appendix

Pros and cons

Benefits

  • Surfaces gaps and misalignments before implementation begins, when the cost of change is lowest.
  • Enables asynchronous review by distributed teams and stakeholders who cannot attend synchronous meetings.
  • Serves as a persistent implementation reference that explains the "why" behind design choices for future maintainers.
  • Creates a shared understanding that makes parallel implementation by multiple engineers safer and more coordinated.

Pitfalls

  • Design docs can become shelfware if the engineering culture does not enforce reading and responding to them before work begins.
  • Over-specification: writing the document at too low a level of detail invites bike-shedding on implementation minutiae rather than architectural review.
  • Approval theater: treating the design doc as a bureaucratic checkbox rather than a genuine alignment tool undermines its value.
  • Stale documents: an approved design doc that is not updated as the implementation deviates becomes actively misleading rather than helpful.

Writing guidance

Write the Overview last. It should be possible for a senior engineer who has not followed the project to read the Overview and understand what is being proposed, why, and how. If the Overview requires background knowledge to parse, it is not ready. Aim for three to five crisp sentences covering: what the system will do, what problem it solves, and the key architectural choice.

The Design section should reflect the level of consensus on the approach. In early drafts, it can be sketchy — the goal is to identify the hardest questions and get reviewers to focus there. As the doc matures through review cycles, fill in detail. Resist the temptation to write exhaustive detail before reviewers have validated the approach; detailed sections that require major rewriting after feedback are wasted effort.

The Alternatives Considered section is often the most scrutinized part of a design review. Reviewers who favor a different approach will look here first to see whether their preferred option was evaluated. Write it honestly — include approaches you considered and found wanting, and explain the specific trade-off that ruled each one out. A good alternatives section demonstrates intellectual honesty and increases reviewer confidence in the proposed approach.

Common mistakes

  • Starting implementation before approval: Encoding work into code before reviewers have had a chance to identify fundamental issues makes the author defensive about feedback and the review superficial.
  • Vague goals: Goals like "improve performance" or "make the system more scalable" cannot be verified and do not bound scope. Every goal should have a measurable success criterion.
  • Missing the Non-Goals section: Omitting non-goals allows stakeholders to interpret scope expansively, leading to out-of-scope feature requests mid-implementation.
  • No security section: Security considerations added late in development are expensive. Even a short, honest security section surfaces risks that the implementation team must account for.

Review checklist

  • Is the Overview self-contained and comprehensible without reading the full document?
  • Does every goal have a measurable or verifiable success criterion?
  • Are at least two alternatives documented with specific rejection rationale?
  • Does the security section address authentication, data sensitivity, and input validation?
  • Is there a concrete rollback plan in the Rollout Plan section?

Example usage

  • New microservice extraction: A team writes a design doc for extracting the billing module from a monolith into a dedicated service, covering the new service's API, the data migration strategy, the dual-write period, and the cutover plan.
  • ML pipeline introduction: A data science team writes a design doc for a new recommendation engine, detailing the feature store schema, model serving architecture, A/B testing framework, and fallback to the existing rule-based system.
  • Infrastructure change: A platform team writes a design doc for migrating the build system from Jenkins to GitHub Actions, documenting the new pipeline architecture, migration plan for 40 existing pipelines, and rollback procedure.

Further reading