A technical spec is only worth writing if it changes a decision before that decision gets expensive. Its entire value is predictive: forcing the hard questions — what happens at scale, what breaks, what was ruled out — onto a page where they are cheap to argue about, instead of leaving them to get answered implicitly by whatever the first engineer to touch the code decides under deadline pressure. A spec written after the fact to satisfy a process checkbox has none of that value, no matter how detailed it is.
What changed in 2026
- AI drafts the skeleton from a rough brief. Given a ticket or a few sentences of context, AI tools now produce a reasonable first-pass structure, though the actual decisions inside it still need a human who understands the tradeoffs.
- Specs link directly to the review thread and any resulting ADR. Fewer specs live as an isolated static document; more are the hub that the design review discussion and the final decision record both point back to.
- One-pagers became normal for small changes. Instead of skipping documentation for anything under a certain size, lightweight one-page specs fill the gap between no doc at all and the full template.
- Diagrams increasingly generate from the actual system. Architecture diagrams pulled from infrastructure-as-code or service dependency graphs are replacing hand-drawn ones that go stale within a quarter.
The sections a spec actually needs
Every section should answer a specific question. If a section cannot answer one, cut it.
| Section |
Question it answers |
| Problem |
What is broken or missing, and why does it matter now |
| Goals and non-goals |
What this spec covers, and explicitly what it does not |
| Proposed approach |
What you are building and how it works |
| Alternatives considered |
What else was possible, and why it was not chosen |
| Rollout and risk |
How this ships safely, and what could go wrong |
| Open questions |
What is still unresolved and needs an answer before or during build |
Sizing the spec to the decision
Not every change deserves the full template. A one-pager — problem, approach, and the biggest risk — is enough for something small and easily reversible. The full structure, including a real alternatives section and a design review, earns its cost only for changes that are expensive to reverse or touch shared systems. Matching the weight of the document to the weight of the decision is what keeps specs from becoming either skipped entirely or resented as overhead.
Writing goals and non-goals that actually prevent scope creep
"Improve checkout reliability" is not a goal; it does not tell anyone when the work is done. "Reduce checkout payment failures caused by timeout errors to under 0.1%" is. Non-goals do the same work in reverse: "this does not address checkout page load time" heads off a scope argument before it starts, because the boundary was drawn on the page instead of negotiated later in a meeting nobody wanted to have.
Alternatives considered: the section people skip
This section is the one most specs shortchange, and it is the one that proves the author actually thought about the problem rather than writing down the first idea. It does not need to be exhaustive — two or three real alternatives, each with a one- or two-sentence reason it was not chosen, is enough to show the reasoning without turning the spec into a survey paper.
Common mistakes
- No non-goals. Without them, scope expands to whatever anyone assumed the spec implied.
- Exactly one alternative, or none. A spec that only describes the chosen approach is a decision, not an analysis.
- Written after the code, for the checkbox. By then it cannot change anything; it can only describe what already happened.
- No open questions section. Pretending everything is resolved is less honest, and less useful, than naming what is still uncertain.
FAQ
How is a technical spec different from a PRD?
A PRD defines what to build and why from a product and user perspective. A technical spec defines how to build it: the architecture, the tradeoffs, and the engineering risk. Complex features often need both. For the product-facing document, see how to write a PRD with AI.
Who should review a technical spec?
The people who own the systems being touched, plus one or two engineers likely to catch a failure mode the author cannot see. The same small-group principle that applies to running a good design review applies here.
How long should a spec take to write?
Proportional to the decision. A one-pager can take an hour. A full spec for a system with real architectural risk is worth a day or two of drafting and iteration, not something to rush before a meeting.
What if the implementation ends up differing from the spec?
Expected and fine, as long as the reason is understood. Update the spec or note the deviation rather than letting the document quietly become fiction that misleads the next reader.
Where to go next