Markdown technical design document template

Copyable technical design template

# Technical design document: [System or change]

**Author:** [Name]  
**Reviewers:** [Names]  
**Status:** Draft  
**Version:** 0.1

## Summary
[Describe the proposed technical change and why it is needed.]

## Context and problem
[Current architecture, problem, evidence, and constraints.]

## Goals
- [Outcome]

## Non-goals
- [Exclusion]

## Requirements

| Requirement | Target |
|---|---|
| Availability | [Target] |
| Latency | [Target] |
| Security | [Control] |

## Proposed design

### Architecture
[Components and data flow.]

### Interfaces and data contracts

```json
{
  "example": "Representative request or event"
}
```

### Data model and migration
[Schema changes, backfill, compatibility, and rollback.]

### Security and privacy
[Authentication, authorization, secrets, logging, and personal data.]

## Alternatives considered

| Option | Advantages | Disadvantages | Decision |
|---|---|---|---|
| [Option] | [Benefits] | [Costs] | Selected/Rejected |

## Failure modes and recovery

| Failure | Detection | Response | Owner |
|---|---|---|---|
| [Failure] | [Signal] | [Recovery] | [Team] |

## Testing and validation
- [Unit, integration, end-to-end, performance, and security checks]

## Rollout plan
1. [Preparation]
2. [Limited release]
3. [Monitoring]
4. [Full release]

**Rollback trigger:** [Condition]  
**Rollback procedure:** [Steps]

## Observability
- **Metrics:** [List]
- **Logs:** [List]
- **Alerts:** [Threshold and owner]

## Open questions
- [ ] [Question] · **Owner:** [Name]

Review the document

Ask reviewers to challenge assumptions, failure handling, migration safety, operational ownership, and rollback. Approval should mean the design is safe enough to implement, not that every sentence is immutable.

Include evidence at the right level

Use diagrams to show boundaries and data flow, but explain the important behavior in text too. Add representative contracts, not every generated schema. Link benchmarks and prototypes, including their test conditions, rather than stating that one option is “faster” without measurements.

For a migration, document old and new readers, backfill order, compatibility window, verification query, and rollback limits. For external dependencies, state rate limits, failure behavior, data residency, and ownership.

Keep implementation aligned

Resolve blocking open questions before implementation reaches the affected area. When the implementation changes a material assumption, update the design or create an ADR. After rollout, record whether targets were met and convert operational details into runbooks where appropriate.

Completed design excerpt

Failure mode: The document-conversion worker exceeds its 30-second execution limit.

Response: Mark the job retryable, retain the source document, retry twice with exponential backoff, then move the job to a review queue. Alert when more than 2% of jobs enter the queue over 15 minutes. The API returns the job ID and a non-success state rather than reporting a completed export.

This excerpt identifies the failure, user-visible behavior, retry limit, retained data and alert threshold. “Handle worker errors” would not be sufficient for implementation or review.

Technical design versus ADR

Use the technical design for the complete behavior of a change. Create an ADR for a consequential choice within it, such as the database, consistency model or integration boundary. Link the two instead of duplicating the reasoning.

Technical design FAQ

When should a design document be written?

Write one before implementation when a change crosses components, changes data, introduces operational risk or needs review by several owners.

Should the document include code?

Include short representative contracts or pseudocode when they remove ambiguity. Link to implementation details that will change frequently.

Who should review it?

Include owners of affected systems and the people responsible for security, data, testing, operations and rollout where relevant.