lockstep
6 min readNaman Jain

Technical design document template (with an example)

A free technical design document template for Google Docs, Confluence, or markdown: sections from Google's design doc practice, an example, and when to skip it.

An engineer spends three days on a design doc for a new notifications service. It gets four comments, a thumbs up, and is never opened again. Eight months later a new engineer asks why notifications go through a queue instead of direct calls, and nobody remembers. The doc had the answer, in paragraph six of a section called "Implementation."

A design doc's long-term value is the trade-offs: what was chosen, what was rejected, and why. This template follows the structure Malte Ubl describes in Design Docs at Google, checked on 16 November 2026, and puts those trade-offs where a reader will find them.

What a design doc is for

A technical design document describes how engineering will build something before the code exists: the high-level approach and the key decisions, with emphasis on the trade-offs. Ubl lists what it does beyond documentation: catching design problems while changes are cheap, building consensus, making sure cross-cutting concerns get considered, spreading senior engineers' knowledge, and forming an organizational memory of design decisions.

It comes after the PRD, which says what to build and why. See PRD vs BRD vs FRD vs SRS for where each document sits.

The template

Paste into Google Docs, Confluence, Word, or a markdown file in the repository:

# [System or feature]: design doc

| | |
|---|---|
| Authors | [Names] |
| Reviewers | [Names] |
| Status | Draft / In review / Approved / Implemented / Superseded |
| Last updated | [Date] |
| PRD | [Link] |

## Context and scope
[The landscape this is built in, and what is being built. Objective
facts only. Link to detail rather than repeating it.]

## Goals
- [What the design must achieve]

## Non-goals
- [Things that could reasonably be goals but are deliberately not]

## Design

### Overview
[One or two paragraphs and a system context diagram.]

### APIs
[Sketch the interfaces that matter to the design. Not full definitions.]

### Data storage
[What is stored, where, and in roughly what shape.]

### Key decisions
| Decision | Chosen | Why |
|---|---|---|
| [Question] | [Option] | [Trade-off that decided it] |

## Alternatives considered
### [Alternative A]
[What it is, what it does better, and why it lost.]

## Cross-cutting concerns
- **Security:** [Impact and how it's addressed]
- **Privacy:** [Data collected, retention, access]
- **Observability:** [Metrics, logs, alerts]
- **Rollout:** [Flags, migration, rollback]

## Open questions
| Question | Owner | Due |
|---|---|---|

How to fill in each section

Context and scope. Bring the reader up to speed fast. Ubl's advice: keep it succinct, assume some knowledge, link to the rest, and stick to objective facts. It isn't a requirements doc.

Goals and non-goals. Non-goals are the more useful half. They aren't negated goals like "shouldn't crash" but things that could reasonably be goals and were deliberately left out. Ubl's example: ACID compliance when designing a database.

Design. Start with an overview, then details. A system context diagram shows how the new system fits among ones readers already know. Sketch the APIs and data storage that matter to the trade-offs; don't paste full schemas or interface definitions, which are verbose and go stale.

Key decisions. Not in Ubl's list, but worth adding: a table of the choices the design rests on. It's the part people come back for.

Alternatives considered. Ubl calls this one of the most important sections. For each alternative, show the trade-off that made it lose. It answers "why didn't you just..." before anyone asks.

Cross-cutting concerns. Security, privacy, observability, and anything else your team always needs. Teams should standardize this list. Ubl notes that Google projects need a dedicated privacy design doc.

A filled-in example

# Notification delivery: design doc

| | |
|---|---|
| Authors | Arjun |
| Reviewers | Mei, Sam |
| Status | Approved |
| Last updated | 16 Nov |

## Context and scope
Today each service calls the email provider directly. Three services
send notifications; a provider outage last month dropped 4,000 emails.
This doc covers a shared delivery service for email and in-app.

## Goals
- No notification lost when a provider is down for up to 1 hour
- One place to add a channel, such as Slack

## Non-goals
- Exactly-once delivery. Duplicates are acceptable; loss isn't.
- User notification preferences UI. Separate project.

## Design
### Overview
Services publish a notification event to a queue. A delivery worker
consumes it, renders the template, and sends through the provider,
retrying with backoff for up to 24 hours.

### Key decisions
| Decision | Chosen | Why |
|---|---|---|
| Sync call or queue | Queue | Survives provider outages; senders don't wait |
| Delivery guarantee | At least once | Exactly once costs a dedupe store we don't need |
| Templates | In delivery service | One copy instead of three |

## Alternatives considered
### Retry in each service
Smallest change, but three retry implementations to keep consistent,
and a crash mid-retry still loses the message.

### Provider's own queueing
Ties us to one provider and doesn't cover in-app notifications.

## Cross-cutting concerns
- **Privacy:** queue payloads hold user IDs, not email addresses;
  addresses are looked up at send time. Queue retention 7 days.
- **Observability:** alert when queue age exceeds 10 minutes.
- **Rollout:** behind a flag per sending service; old path kept 2 weeks.

When not to write one

Ubl is direct that design docs are overhead. Write one when the solution is ambiguous, through problem complexity, solution complexity, or both. If the doc would only say "this is how we'll implement it," with no trade-offs or alternatives, write the code instead. A working prototype is one of the best arguments for a design.

For smaller, incremental changes, a 1 to 3 page mini design doc covers the same steps more briefly. For larger projects, Ubl puts the sweet spot around 10 to 20 pages.

Keeping the decisions alive

Design docs drift out of sync with the system once it ships, Ubl notes, but they remain the first place engineers look to understand why. The decisions inside them are what matter most later, and they're buried in prose. Two habits help: record each significant decision as an architecture decision record next to the code, and mark the doc Superseded, with a link, when the design changes.

Where Lockstep fits

Lockstep pulls the decisions out of design docs, PRDs, Slack threads, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions with the ones that apply to the code being changed. A session refactoring the delivery worker gets "at least once, not exactly once, and why" before it starts, rather than an agent rediscovering it from paragraph six.

See how it works.

Sources checked 16 November 2026

For recording individual decisions, see the ADR template and decision log vs ADR. For ADRs that AI coding agents read, see ADRs for AI coding agents. For writing up incidents, see the blameless postmortem template. For proposals that need a review process, see the engineering RFC template. For choosing between document types, see ADR vs RFC vs design doc vs PRD. For operating what you build, see the runbook template. For the diagrams in a design doc, see architecture diagram examples. For reviewing a design, see the architecture review template.

Frequently asked questions

What is a technical design document?
A document engineers write before building a system or major feature, describing the high-level implementation approach and the key design decisions, with emphasis on the trade-offs considered. It's also called a design doc, technical spec, or software design document.
What should a technical design document include?
Context and scope, goals and non-goals, the proposed design (often with a system context diagram, API sketch, and data storage), alternatives considered with their trade-offs, and cross-cutting concerns such as security, privacy, and observability. Add open questions and a rollout plan if useful.
How long should a design doc be?
Long enough to explain the trade-offs and short enough for busy people to read. Malte Ubl's account of design docs at Google puts the sweet spot for larger projects around 10 to 20 pages, and notes that 1 to 3 page mini design docs work for smaller, incremental changes.
What is the difference between a PRD and a technical design document?
A PRD says what to build and why, from the user's side. A technical design document responds with how engineering will build it: architecture, interfaces, data, and the trade-offs behind each choice. Product usually writes the PRD first.
When should I not write a design doc?
When the solution isn't ambiguous. If the doc would just say how you'll implement something, with no real trade-offs or alternatives, writing the code directly is usually better. Design docs earn their cost on problems that are complex, contentious, or expensive to get wrong.

Keep reading