Skip to content

Technical Design Document

First PublishedByAtif Alam

Before building a script, service, CLI, scheduled job, or internal tool, write down what problem you are solving, how you will build it, and what could go wrong.

This page is a Technical Design Document template you can copy and fill in for that purpose.

Use this for small and medium software. Depth can scale up as risk grows — you do not need a second template, only more detail. Multi-service or high blast-radius designs should also pass a structured review (see below).

Related: Agile for SRE and platform work (toil → automate), Design review checklist (large distributed systems), Service readiness checklist (pre-prod gates after build).

Template

Section titled “Template”

Copy the sections below into a new doc (or PR description). Replace the prompts with your answers. Title the copy with the component name: for example Widget Sync — Technical Design Document.

1. Overview

Section titled “1. Overview”

One paragraph: what does this software do, end to end?

2. Problem and Goal

Section titled “2. Problem and Goal”
  • What manual process, outage class, or product gap does this replace or fix?
  • What does done / working look like? How will you know it succeeded?

3. Scope

Section titled “3. Scope”
  • In scope: core behavior this work must deliver.
  • Out of scope: anything explicitly deferred (and why).

4. Data Source / Inputs

Section titled “4. Data Source / Inputs”
  • Where does input come from? (database, API, file, queue, user CLI flags, another service)
  • What is the shape/format of that data?
  • Any auth or credentials needed to access it?

5. Destination / Output

Section titled “5. Destination / Output”
  • Where does output go? (API write, object store, wiki/ticket system, metrics, filesystem, stdout)
  • What does a successful update look like?
  • Does a rerun overwrite, append, or skip existing records?

6. Architecture and Execution

Section titled “6. Architecture and Execution”
  • Repo: new repository or existing? Which monorepo package or service directory?
  • Execution environment: cron, cloud function, Kubernetes CronJob or Deployment, CI scheduled pipeline, long-running service, manual CLI?
  • Run frequency: continuous, daily, on event, on-demand?
  • Triggered by / owned by: who or what kicks it off, and who is on call if it fails?

7. Tech Stack

Section titled “7. Tech Stack”
  • Language and major libraries/SDKs.
  • Integrating into an existing codebase, or standalone?
  • Why this stack (team skill, latency, packaging, reuse of existing modules)?

8. Existing Code Alignment

Section titled “8. Existing Code Alignment”
  • Patterns to follow in the target repo (logging, config/secrets, errors, retries).
  • Utility modules or shared libraries to reuse.
  • Style, lint, and review conventions for that repo.

9. Integration Points

Section titled “9. Integration Points”
  • External APIs or services touched.
  • Auth mechanism (API token, OAuth, service account, mTLS).
  • Rate limits, quotas, or SLAs to respect.

10. Testing Strategy

Section titled “10. Testing Strategy”
  • Unit tests: what pure logic needs coverage (transforms, formatting, decision rules)?
  • Integration tests: real or mocked external systems?
  • Manual / acceptance check: how do you confirm behavior matches expectations before enabling the schedule or rollout?

11. CI/CD Integration

Section titled “11. CI/CD Integration”
  • Do tests run automatically on commit or PR?
  • Is deploy, packaging, or scheduling automated, or still manual setup?
  • Rollout and rollback: feature flags, canary schedule, or single cutover?

12. Open Items and Assumptions

Section titled “12. Open Items and Assumptions”
  • Unresolved questions to settle before or during implementation.
  • Assumptions that, if wrong, force a redesign.

13. Risks and Unknowns

Section titled “13. Risks and Unknowns”
  • Anything that could change the design (API limits, data quality, permissions, cost, compliance).
  • Blast radius if the job fails or runs twice.

Safety Defaults

Section titled “Safety Defaults”

Write these into the design when the work mutates systems or data:

  • Prefer a dry-run / no-op mode (preview changes without applying them) when the domain supports it — tools vary (Ansible check mode, Terraform plan, kubectl apply --dry-run, custom --dry-run flags). See Ansible playbooks and CI/CD policy as code.
  • Design for idempotent runs where practical (safe retries without double side effects). Module and API patterns: Ansible modules, REST HTTP fundamentals.
  • Keep secrets out of the repo; load from the platform’s secret store or CI secrets. Never log tokens.
  • Name an owner and a failure signal (alert, ticket, CI fail) — see Incident tooling and customer communications.

What The Industry Usually Calls These

Section titled “What The Industry Usually Calls These”

These names overlap. Orgs mix them by size and culture. Pick the label your team already uses — the work is the same: decide before you code.

TermTypical meaning
PRD (Product Requirements Document)Product/PM lens: who the user is, problem, features, success metrics, non-goals. Light on how you build or deploy.
Design Doc (Engineering Design Document)Engineer-owned (Google-style and many mid/big-tech orgs): problem, goals, proposed design, alternatives, rollout, testing, risks. Common label for “plan software before coding.”
Technical Design Document / Tech SpecDeeper “how we build it” (APIs, data models, sequencing, stack, execution). Often the eng-owned technical half of planning.
RFC (Request for Comments)Same spirit as a design doc, framed for peer review and a decision.
ADR (Architecture Decision Record)One architecture decision + context + status (accepted/superseded) — not a full plan.
Project Brief / One-Pager / Tech BriefShort problem + goal + scope + owner for small work; often the outer shell before a longer tech write-up.
Functional SpecWhat the system does from the outside (behavior/I/O) without full stack/CI detail.

In many teams, the acronym TDD means Test-Driven Development (write tests first). On this page, “Technical Design Document” is never shortened to bare “TDD” — if your org says “TDD,” clarify which meaning you mean.

How This Page Maps

Section titled “How This Page Maps”
Part of the templateClosest industry label
Problem, goal, scope, success criteria, I/OPRD-like (what / why)
Execution environment, stack, integrations, tests, CI/CD, risksTechnical design (how / where / how we know it works)
  • A page titled only PRD would under-describe the engineering sections above.
  • A page limited to script checklists would over-narrow the audience — the same outline works for any small or medium piece of software.
  • For large work, the usual split is a product or project brief (PRD-ish) plus a deeper design doc, tech spec, or RFC. Scale depth in these sections rather than inventing a second outline.
  • When the design is multi-service or high blast radius, pair this document with a design review checklist.

When To Write One

Section titled “When To Write One”

Write a short technical design document when any of the following is true:

  • Another human (or future you) must understand the design without the author present.
  • The work touches external systems, credentials, schedules, or production data.
  • You need agreement on scope, ownership, or “done” before coding.
  • The change might become a permanent team dependency (toil automation, shared tool, library).

Skip a formal write-up only for throwaway experiments that will not leave your laptop — and still jot problem + goal if the experiment might graduate.

Checklist Before Coding

Section titled “Checklist Before Coding”
  • Problem, goal, and “done” are written in plain language.
  • In / out of scope is explicit.
  • Inputs, outputs, and overwrite-vs-append behavior are stated.
  • Where it runs, how often, and who owns failures are named.
  • Stack and repo alignment notes exist.
  • Integrations and auth are listed (no secrets in the doc — names of secret keys only).
  • Test and CI approach is clear enough to implement.
  • Open items and risks have owners or a plan to resolve them.
  • Large / multi-service designs have used or scheduled a design review.
Section titled “Related”