When done poorly, they’re ignored, debated endlessly, or written as formalities after the decision is already made.

This post is about writing TDDs that work: getting the right people to the right decision with minimum friction.

When to Write a TDD (and When Not To)

Not every technical change needs a design document. Writing an unnecessary TDD creates process overhead without benefit. A useful heuristic:

Write a TDD when:

• The change affects more than one team or system
• There are multiple viable approaches with real trade-offs
• The change is hard or expensive to reverse
• The implementation will take more than 1–2 weeks
• Stakeholders outside engineering need to understand the approach

Don’t write a TDD when:

• The approach is already obvious to everyone involved
• It’s a well-understood pattern you’ve applied before
• The cost of getting it wrong is low and easy to fix
• You’re implementing exactly what was already decided in a previous TDD

The signal for skipping a TDD: if you sat down to write one and there’s nothing non-obvious to decide, you don’t need it.

One exception: when you’re new to a team, writing a TDD even for straightforward work builds trust and gives reviewers a window into your thinking. The value there isn’t the document — it’s the review conversation.

The Sections That Actually Matter

Design documents have a lot of conventional sections. Most of them are useful. A few are often missing.

Problem Statement

This section is frequently too thin. Engineers jump to the solution before establishing the problem clearly enough. A strong problem statement answers:

• What is broken, missing, or insufficient today?
• What is the impact of the current state? (User impact, system impact, operational cost)
• What evidence establishes that this problem is real and worth solving?
• What is the scope of the problem? (One team? The whole platform? A specific user segment?)

If readers don’t understand the problem deeply, they can’t evaluate proposed solutions. Invest more time here than you think you need.

Goals and Non-Goals

Goals should be specific and testable, not vague aspirations. “Improve reliability” is not a goal. “Reduce p99 latency for the checkout API from 2s to 400ms under 1,000 RPS” is a goal.

Non-goals are equally important and often omitted. Non-goals:

• Set scope explicitly (prevents the review from expanding into adjacent problems)
• Signal that you’ve thought about what you’re deliberately not solving
• Protect the design from being evaluated against requirements you never intended to meet

Write non-goals as explicit statements, not silence. “We are not solving X in this proposal” is useful. Leaving X unmentioned is not.

Background and Context

What does a reviewer need to know to evaluate this document who isn’t deep in this area? Include:

• How the relevant systems currently work (high-level)
• Prior attempts to solve this problem and why they failed or were abandoned
• Constraints that shape the solution space (regulatory, contractual, legacy dependencies)
• Why now — what changed that makes this worth solving today

This section is easy to underwrite if you assume shared context. Assume less than you think you should.

Proposed Solution

The meat of the document. Structure it to answer:

• What is the approach at a high level?
• What are the key components or changes?
• How does it satisfy each of the stated goals?
• How do the pieces interact? (A sequence diagram or system diagram often conveys this better than prose)

Resist the urge to write this section before the others. Engineers who jump to the solution first often write problem statements that are shaped to justify the solution they already want. Write the problem clearly first, then write the solution.

Alternatives Considered

This section is not filler. It’s evidence that you explored the space seriously.

For each alternative:

• What is the approach?
• Why might it be preferable?
• Why are you recommending against it?

The alternatives section also protects you. When a reviewer proposes what you considered and rejected, you can point here instead of relitigating it in the review. It also signals to leadership that you didn’t pick the first thing that worked.

Don’t list alternatives you didn’t seriously consider. One sentence strawmen waste everyone’s time.

Risks and Open Questions

Name the risks explicitly:

• What assumptions does this design rely on?
• What could go wrong during implementation?
• What dependencies could block or invalidate this approach?
• What happens to existing users/systems during the transition?

Open questions deserve a section because they’re honest. Not everything is decided when you write the document. Naming open questions tells reviewers where you need input, and it triggers the right conversations.

Mark open questions with an owner when possible: “Decision needed from platform team: [question].” Unowned open questions don’t get resolved.

Implementation Plan and Rollout

Cover:

• What’s the phased rollout plan? (Especially important for changes with production impact)
• What’s the rollback plan?
• What observability will you add to know if it’s working?
• What’s the migration path for existing data or users?
• What’s the timeline and what are the dependencies?

The implementation section separates documents that drive action from documents that sit in a wiki. Reviewers want to know not just what you’re building but how you’ll build it safely.

Writing for the Right Audience

Most TDDs have multiple audiences with different needs:

Technical reviewers (the engineers who will implement this or maintain related systems) need the depth: specific design choices, data models, API contracts, failure modes.

Cross-functional stakeholders (product, data, security, legal) need the impact and the trade-offs, not the implementation details. If you’re sharing a doc with this group, a one-page executive summary at the top saves everyone time.

Future engineers reading this six months later need context they don’t have: why was this chosen over alternatives, what was the state of the system at the time, what constraints applied.

Write with all three in mind. Structure the document so reviewers can navigate to the parts relevant to them. Bury the deeply technical detail in sections that cross-functional stakeholders can skip.

The Review Process

A TDD with no review process is a document, not a decision mechanism. Structure the review deliberately.

Set a deadline. “Please review by Friday EOD” produces responses. “Let me know when you’ve had a chance to look” produces silence.

Designate required reviewers vs. optional. Required reviewers must sign off. Optional reviewers get to weigh in but can’t block. Be explicit about who is in each category.

Time-box the comment period. Two weeks of open-ended review often results in more confusion than a focused 3-day window. Scope creep in review is a real problem.

Hold a synchronous review meeting for high-stakes designs. Async comment threads are efficient for small details. For designs that affect multiple teams or have significant architectural implications, a 1-hour synchronous review often resolves more than 2 weeks of async back-and-forth.

Distinguish blocking feedback from non-blocking. Reviewers should label comments: “blocking” (must be addressed before approval), “suggestion” (take or leave), “question” (just curious). This prevents good-faith questions from becoming approval blockers.

Common Failure Modes

Written after the decision. The TDD is created to document what’s already been decided, not to make the decision. Reviewers are asked to ratify, not evaluate. This produces rubber-stamp reviews and skips the alignment that makes TDDs valuable. The fix: write the TDD before writing code, not after.

Too long to read. A 30-page design document gets skimmed or skipped. If your TDD is over 10 pages, it’s probably covering too much scope or including implementation details that belong in code comments. Aim for 3–6 pages of substantive content.

Pitched at the wrong level. A highly technical document sent to a VP-level audience, or a high-level document sent to engineers who need to implement it. Write the right document for the right audience, or write a document with a layered structure.

Alternatives section that’s a formality. One-line alternatives that obviously weren’t seriously considered signal that you’ve already decided and are going through the motions. If you can’t write a genuine case for each alternative, remove it — or go back and do the exploration.

Never updated. The design changes during implementation but the document doesn’t. Later engineers read the original document and draw wrong conclusions. Either keep the document updated or add a prominent note: “Implementation diverged from this design in the following ways: [link to followup doc].”

Living Documents vs. Archived Decisions

Some TDDs stay relevant long after implementation — architectural decisions, data model choices, API contracts. These should be kept in a stable location and updated when the design evolves.

Others are point-in-time decisions that become irrelevant after implementation. For these, mark them clearly: “This design was implemented in Q3 2026. The system now works as described. For current architecture, see [link].”

The worst outcome is a design document that describes something that no longer exists, sitting in the same location as current documentation with no indication that it’s outdated.

A Minimal TDD Template

Title: [What this designs]
Status: Draft / In Review / Approved / Implemented
Author: [Name]
Reviewers: [Required] / [Optional]
Created: [Date]
Last Updated: [Date]

---

## Problem Statement
[What is broken, missing, or insufficient? What's the impact?]

## Goals
- [Specific, testable goal 1]
- [Specific, testable goal 2]

## Non-Goals
- [Explicitly out of scope: X]
- [Explicitly out of scope: Y]

## Background
[Context reviewers need. Prior attempts. Constraints.]

## Proposed Solution
[High-level approach. Key components. How it satisfies the goals.]

## Alternatives Considered
### Option A: [Name]
[Description, pros, why rejected]

### Option B: [Name]
[Description, pros, why rejected]

## Risks
- [Risk 1: impact, likelihood, mitigation]
- [Risk 2: ...]

## Open Questions
- [Question] — Owner: [Name], Needed by: [Date]

## Implementation Plan
- Phase 1: [...]
- Phase 2: [...]
- Rollback plan: [...]
- Observability: [...]

The template is a starting point. Add sections when your design needs them. Remove sections when they’d be empty. A TDD that follows a template perfectly but says nothing useful is worse than no TDD at all.