A Technical Design Document Template

A short technical design document: the problem, the constraints that already exist, the options, and the one you are proposing.

A technical design document is the proposal you want reviewed before anyone writes the code. An architecture decision record is the short note you keep after the choice is made. Write the design document while the choice is still open. If you only keep the decision, the next person sees what you chose and not what you rejected.

Long templates get left half filled, and the real constraints show up in the review meeting. Put the constraints in the document.

The template

docs/design/short-title.md

# Short title

Author:
Date:
Status: Draft | In review | Decided (link the ADR)

## Problem
What is wrong, or what you are trying to make possible.
Two or three sentences.

## What already constrains us
Facts that rule options out. Incidents, decisions, capacity, ownership.
If this section is empty, you have not looked yet.

## Options
- Option. What it costs. Why it might be wrong.
- Option. What it costs. Why it might be wrong.

## Proposal
The option you want, and the trade-off you are accepting.

## Open questions
What you need the review to answer.
If this section is long, the document is not ready.

A filled-in example

docs/design/billing-job-lock.md

# Stop the nightly billing job running twice

Author: Priya
Date: 2026-03-03
Status: Decided (docs/adr/0007-advisory-lock-on-billing.md)

## Problem
A deploy overlapped the cron window. The job started on both app
servers and some customers were charged twice.

## What already constrains us
Refunds are a billing-team action. The job runs once a night, so a
lock that lasts until the connection dies is acceptable. We are not
adding a queue for this.

## Options
- A database advisory lock, and the second copy exits. Small change.
  A hung job holds the lock until the connection dies.
- Move the cron off the app servers. Right later, too big for the fix.

## Proposal
The advisory lock. We accept the hung-connection case while billing
runs once a day.

## Open questions
Sam to confirm the lock key does not collide with the report job.

The constraints section is what makes the review shorter. Without it, every reviewer reconstructs the same limits from memory, or from a postmortem they may not find. With it, the review is about the proposal.

Start from constraints you already have

Prodigent surfaces the incidents, decisions, and owners that belong in that section, so the document does not start from a blank page.

Try Prodigent free