You came for a technical design document template — the sections, the headings, something to paste in before you start building. It's below; take it. But know the failure mode you're inheriting: a TDD is written once against a PRD, and the PRD never stops moving. Someone reframes the requirement, the design doc in docs/design/ or on a Confluence page doesn't move with it, and the implementation drifts from a spec the whole team still trusts. Draftlize gives you the same eight sections — and makes each one a card linked to the decisions it rests on, so the moment an upstream call changes, the design doc flips to drift_detected and your coding agent reads the corrected design, not the stale one.
This is the whole template — a software design document in the shape engineers actually use. It works in a markdown file, a wiki, or a Google Doc. Use it as-is. The next section is about what changes when each heading stops being prose under a PRD nobody re-reads and becomes a card that knows when its premises moved.
What you're building and the one-line problem it solves, with a link up to the PRD that asked for it. The PRD says what and why; this doc starts where that leaves off and says how.
What this design is responsible for — and, just as load-bearing, what it deliberately is not. The non-goals are the line you point at six weeks later when someone asks why the system doesn't do the thing it was never meant to.
The components, how they talk, and where the boundaries are. A diagram and the prose that defends it. This is the section a reviewer reads first and the one most likely to be quietly invalidated when an upstream decision changes.
The entities, their fields, the relationships, and the migrations. Where state lives and who owns it. Get this wrong and every API below inherits the mistake — which is why it sits above the API section, not beside it.
Endpoints or interfaces, request and response shapes, error semantics, and versioning. The contract other teams build against — so it has to stay honest about what the system actually exposes, not what it exposed at design time.
The alternatives you weighed and the one you chose, with the reason. The section your future self opens to understand why it's built this way. Most TDDs skip it; it's the part that ages best when it's there.
The failure modes you can foresee — scale, consistency, the dependency that might not hold — and what you'll do about each. Honest risk is cheaper to write here than to discover in an incident.
Phases, feature flags, the migration order, and the rollback. How this design becomes a running system without a big-bang cutover — and how you back out if a premise turns out wrong in production.
That's the template. Below: why it drifts from the PRD the day after you write it — and what we do about it.
People reach for "design doc" and "PRD" interchangeably, and that's exactly how implementations go sideways. They answer different questions, and the TDD is downstream of the PRD — which is why it's the one that silently rots when the PRD moves.
A product requirements doc is about the problem — the user, the outcome, the success metric, the constraints. It deliberately doesn’t say how. “Users can recover an account without contacting support” is a PRD line. It says nothing about tokens, tables, or endpoints, on purpose.
A technical design document is about the solution — the architecture, the data model, the API, the trade-offs that get you from that requirement to running code. It’s where “recover without support” becomes a signed token, a password_reset table, and a rate-limited endpoint with a rollout plan.
Because the design is built on the requirement, every change to the PRD ripples down. Tighten the requirement to “recover within 60 seconds, no email” and the token-and-email design is now wrong — but the design doc doesn’t know that, and nobody re-opens it to find out.
The TDD is most accurate the hour you finish it — pinned to the PRD as it read that day. But the PRD keeps moving: a requirement gets reframed in a meeting, a constraint loosens, a decision upstream flips. The design doc stays frozen at the moment of writing while the thing it was designed against walks away.
Your Proposed architecture rests on a decision — “we’re multi-tenant,” “we don’t need real-time.” In markdown that assumption is a sentence, not a link. When the decision changes, no signal reaches the design doc, so the architecture quietly describes a system you’re no longer going to build.
Updating the design doc to match the new PRD is a chore that competes with writing the code, and the code always wins. So docs/design/ freezes, the implementation tracks the conversation in the PR instead, and the gap between the documented design and the running system widens every sprint.
In Draftlize the TDD isn’t a wall of prose — each section is a typed card: Overview, Goals & non-goals, Proposed architecture, Data model, API design, Key trade-offs, Risks & mitigations, Rollout plan. Structured, addressable by ID, and citable from a thread or another spec instead of buried in a Confluence tree.
Each section links to the upstream PRD lines and decisions it rests on. Change one of those, and every design card built on it flips to drift_detected — the way a build system invalidates everything downstream of a changed file. The design doc tells you it’s out of sync the moment it is, instead of misleading the next reader.
Claude Code or Cursor, over MCP, pulls the relevant design cards before it writes code — and because drift surfaces, it reads the corrected architecture, not the version that matched last month’s PRD. The design doc stops being a write-once artifact and becomes context the agent reads on every turn.
A design doc is a bet on a spec that won’t hold still. Stop re-syncing it by hand; let it flag itself when the spec moves.Keep the eight sections. Link them to the decisions underneath, and let drift surface.
A technical design document describes how you will build something before you build it — the architecture, the data model, the API design, the key trade-offs, and the risks. It exists so the hard decisions are made and reviewed on paper, where they are cheap to change, instead of discovered halfway through the implementation.
Overview, goals and non-goals, proposed architecture, data model, API design, key trade-offs, risks and mitigations, and a rollout plan. Non-goals and trade-offs are the sections that age best: they record what you deliberately ruled out, so nobody reopens a settled question six months later.
A PRD says what to build and why — the problem, the users, the requirements. A technical design document says how to build it — the architecture and the engineering decisions that satisfy the PRD. The PRD is the input; the TDD is the engineering answer to it.
Re-syncing a design doc by hand loses to shipping every time. Draftlize links each section to the PRD lines and decisions it rests on, so when one moves the design card flips to drift_detected — the doc tells you it is out of sync the moment it is, and a coding agent reads the corrected design instead of the one that matched the previous PRD.
Take the template above, or spin up a project, link your TDD sections to the PRD and decisions they rest on, and connect your coding agent over MCP — so the design stays in sync with the spec, and flags drift the moment a requirement moves.
Start free with $5