Technical specification template

Published 19 October 2026

A technical specification says how software will be built: the architecture, the data, the interfaces, and the trade-offs behind each choice. Teams also call it a tech spec, a design doc, a technical design document (TDD) or a software design document (SDD). Below are a template, a filled-in example, an architecture decision record (ADR) template, and how to write a tech spec and keep it true.

A technical specification describes the internal implementation of the program. It talks about data structures, relational database models, choice of programming languages and tools, algorithms, etc.

— Joel Spolsky, Joel on Software, 2000

Technical vs functional specification

The functional side has its own functional specification template. A technical specification starts where that one ends, and names the requirements it implements — so that when a requirement changes, the part of the design written for it can be found.

What goes in a technical specification

1. Context and scope: what is being built, and the landscape around it.
2. Goals and non-goals: what the design must achieve, and what it deliberately does not.
3. Requirements: the functional and non-functional requirements it implements, by ID.
4. The design: an overview first, then the components, the data model, the interfaces and the main flows.
5. Alternatives considered, and why each lost.
6. Cross-cutting concerns: security, privacy, performance, monitoring.
7. Rollout: migration, feature flags, how to roll back.
8. Testing: how the design will be checked.
9. Risks and open questions, each with an owner.
10. Changes: what changed after review, and why.

Google’s design docs follow a similar shape. Malte Ubl, who wrote about them, lists context and scope, goals and non-goals, the actual design, alternatives considered and cross-cutting concerns, and says of the first section: “This isn’t a requirements doc. Keep it succinct!” (Design Docs at Google, 2020).

Technical specification template

Copy it into Google Docs, Confluence, Word or a markdown file in the repository. Square brackets are yours to fill in.

TECHNICAL SPECIFICATION
[feature or system]

Author:    [name]
Reviewers: [names]
Status:    [draft / in review /
           approved]
Approved:  [name], [date]
Version:   [x.y], [date]

1. CONTEXT AND SCOPE
   [what is being built, and around
   what]

2. GOALS AND NON-GOALS
   Goals:      [   ]
   Non-goals:  [   ]

3. REQUIREMENTS
   [FR-n, NFR-n], from [document],
   version [x.y]

4. DESIGN
   Overview:    [one paragraph]
   Components:  [   ]
   Data:        [tables, fields]
   Interfaces:  [APIs, events]
   Main flows:  [steps or a diagram]

5. ALTERNATIVES CONSIDERED
   [option]:  [why not]

6. CROSS-CUTTING CONCERNS
   Security:     [   ]
   Privacy:      [   ]
   Performance:  [   ]
   Monitoring:   [   ]

7. ROLLOUT
   [migration, flags, rollback]

8. TESTING
   [   ]

9. RISKS AND OPEN QUESTIONS
   [question]:  [owner], by [date]

10. CHANGES
   [x.y], [date]:  [what, and why]

Technical specification example

The customer portal from the other templates: card payments for open invoices.

TECHNICAL SPECIFICATION
Card payments for open invoices

Status:    approved
Approved:  tech lead, 14 March
Version:   1.1, 14 March

1. CONTEXT AND SCOPE
   Customers pay invoices by bank
   transfer today. This adds card
   payment to the customer portal.

2. GOALS AND NON-GOALS
   Goals:      pay an open invoice by
               card; receipt by email;
               never charge twice
   Non-goals:  saved cards; refunds
               (done by the accounts
               team, as today)

3. REQUIREMENTS
   FR-014, FR-015, NFR-007, from
   requirements version 1.3

4. DESIGN
   Overview:  the portal opens a
     payment session at the provider;
     the customer pays on the
     provider's hosted page; the
     provider calls the portal back.
   Components:  portal API, payment
     provider, email queue
   Data:  payments table: id,
     invoice_id, provider_id, status,
     amount, created_at
   Interfaces:
     POST /invoices/{id}/payments
       returns the provider's URL
     POST /webhooks/payments
       signed by the provider
   Main flows:
     1. Session is created with the
        invoice ID as its key, so a
        second click reuses it.
     2. Webhook "succeeded": invoice
        marked paid, payment saved,
        receipt queued.
     3. No webhook in 60 s: the
        portal asks the provider for
        the status before any retry.

5. ALTERNATIVES CONSIDERED
   Card fields on our own page:
     card data would pass through
     our servers. Rejected (ADR-4).
   Bank transfer links only: does
     not shorten payment time
     (BR-03). Rejected.

6. CROSS-CUTTING CONCERNS
   Security:  card details never
     reach our servers; webhook
     signatures checked
   Performance:  session created
     within NFR-007's 2 seconds
   Monitoring:  failed payments
     logged with the bank's reason;
     alert at 5 in 10 minutes

7. ROLLOUT
   Feature flag; 10 customers first,
   then everyone after two weeks.

8. TESTING
   Provider's test cards; UAT-01,
   UAT-02 in the UAT test plan.

9. RISKS AND OPEN QUESTIONS
   Provider outage: customers see
   "Card payment unavailable" and
   can still pay by transfer.

10. CHANGES
   1.1, 14 March: idempotency key
   added after review (flow 1).

The design answers to the use case UC-03: its minimal guarantee — the card is charged at most once — is flow 1, and its extension 5b, the bank that does not answer, is flow 3.

Architecture decision record (ADR) template

Some choices outlive the feature they were made for. An architecture decision record keeps one decision, with its reasons, next to the code. The format comes from Michael Nygard, who proposed keeping “a collection of records for “architecturally significant” decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques” (Cognitect, 2011).

ADR-[n]: [short noun phrase]

Status:   [proposed / accepted /
          superseded by ADR-n]
Date:     [date]

Context
[the forces at play: facts, not
opinions]

Decision
We will [   ].

Consequences
[what follows, good and bad]

Filled in:

ADR-4: Hosted payment page

Status:   accepted
Date:     10 March

Context
Card fields on our own page would
put our servers in the path of card
data, with the security work that
brings. The provider offers a hosted
page.

Decision
We will send customers to the
provider's hosted page to pay.

Consequences
+ Card data never reaches us.
- The payment page looks like the
  provider's, not ours.
- A provider outage stops card
  payments; transfer still works.

Decisions that are not architectural — a priority, a scope call, an answer to an open question — go in a decision log, with a line there for each ADR.

Design doc vs RFC vs ADR vs software design document

IEEE 1016-2009, the standard for software design descriptions, is listed by IEEE as an “Inactive-Reserved Standard” (IEEE). Note that in AI coding, SDD also stands for spec-driven development.

How to write a technical specification

1. Start from the agreed requirements. Name the version you are designing against; a design built on requirements that are still moving moves with them.
2. Write the context and the goals first, and get them reviewed. One commenter describes their favourite pattern at Google: “The green doc is typically a “one pager” (basically always 2 pages at Google) and it typically never discusses implementation details.” The detailed design comes after (Hacker News, 2021).
3. Prototype the part you are unsure of. An engineer who wrote design docs at Google: “I cannot write a realistic non-hand-wavy design document without having a proof of concept working” (Hacker News, 2026).
4. Write the trade-offs, not only the result. Alternatives considered, and why each lost, are what a reader a year later needs most.
5. Cover the cross-cutting concerns — security, privacy, performance, monitoring — even in one line each.
6. Keep it short. Ubl: “The sweet spot for a larger project seems to be around 10-20ish pages.” A small change can have a one- to three-page “mini design doc”.
7. Get it reviewed, and record who approved which version.

Keeping a technical specification current

Approval is the start of its life, not the end. One commenter:

Design docs go out of date pretty fast. I think it’s healthy to treat design docs like a historical artifact - true at one point in time.

— Hacker News, 2024

Another, on what happens “after the doc is approved”: “Without upkeep it decays into “design archaeology.”” (Hacker News, 2025).

What helps:

• A version and a date at the top, and a changes section.
• Changes after approval go back to the reviewers. One commenter’s rule of thumb: “Is there a chance my reviewers would not have signed off had this been in the design doc they reviewed?” If the answer is yes, they “send it out for a follow-up and explain why I had to change the design” (Hacker News, 2026).
• Decisions that outlive the feature become ADRs, kept with the code.
• The requirements it implements, by ID and version, so a changed requirement points to the design that needs another look.

Technical specifications and AI coding agents

In GitHub’s Spec Kit, the technical plan sits between the spec and the code. It describes the flow as: “Define what to build and why, then turn the specification into a plan, tasks, and working code” (Spec Kit). The plan is a technical specification: its example is “Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite.”

Someone who teaches workshops on AI coding tools put it this way: “this isn’t a new workflow invented for AI - it’s how good senior engineers already work. You read the code deeply, write a design doc, get buy-in, then implement.” (Hacker News, 2026). The spec.md template covers the “what and why” side.

Where Specroot fits

This is the problem Specroot works on: a technical design tied to the version of the requirements it implements, so that when a requirement changes, the design written for it is easy to find and review again. Specroot for teams using AI coding agents.