17 juni 2026Bijgewerkt op Fathy Shalaby13 min leestijd
Technische spec-template: schrijf een spec die engineers echt lezen
Een te kopiëren technische spec-template, de design-doc- en RFC-praktijken waar hij op leunt en een stapsgewijze methode voor een spec die engineers tot het eind lezen.
Een technische spec-template zet de riskante beslissingen op pagina één: het probleem en de randvoorwaarden, het voorgestelde ontwerp, de alternatieven die je hebt afgewezen en wat er mis kan gaan, bij de meeste wijzigingen op één tot drie pagina's. Google-design docs en Uber-RFC's volgen deze opzet. De template hieronder om te kopiëren voegt een samenvatting in één zin en een beslissingstabel toe, zodat reviewers de lastige keuzes in minder dan een minuut vinden.
Belangrijkste punten
Google-design docs hebben vijf kernonderdelen en beslaan 10 tot 20 pagina's bij grote projecten, maar 1 tot 3 pagina's bij incrementeel werk (Malte Ubl, 2020).
Lezers komen op een gemiddelde webpagina door ongeveer 20% van de woorden, hooguit 28% (Nielsen Norman Group, 2008). Specs worden net zo gelezen: je scant ze op de stukken die fout kunnen zijn.
61% van de developers besteedt meer dan 30 minuten per dag aan het zoeken naar antwoorden (Stack Overflow, 2024). Een spec die beslissingen vastlegt, beantwoordt die vragen één keer.
Teams met goede documentatie passen 3,8 keer zo vaak security best practices toe (DORA, 2021).
„Overwogen alternatieven” is het onderdeel waar reviewers het meest op vertrouwen, omdat het laat zien dat je naar een reden hebt gezocht om het niet zo te bouwen.
Wat is een technische spec, en hoe verschilt die van een PRD?
Een technische spec (ook wel design doc of technisch ontwerpdocument genoemd) legt uit hoe een team iets gaat bouwen en welke afwegingen het daarbij accepteert. Een PRD legt uit welk probleem het oplossen waard is, voor wie, en hoe succes wordt gemeten. Het PRD komt eerst; de technische spec is het antwoord erop.
Teams gebruiken vier verwante documenten. Ze door elkaar halen is de meest voorkomende reden dat een spec uitgroeit tot 15 pagina's die niemand uitleest.
Welk probleem, voor wie, en hoe weten we dat het gewerkt heeft?
Product manager
2–5 pagina's
Technische spec / design doc
Hoe gaan we het bouwen, en welke afwegingen maken we?
Tech lead of engineer
1–3 pagina's (10–20 bij grote systemen)
RFC (request for comments)
Is de rest van de organisatie het eens met dit plan voordat het werk begint?
Auteur plus genoemde goedkeurders
Als een spec, met een reviewdeadline
ADR (architecture decision record)
Waarom hebben we deze ene beslissing genomen, en wat volgt eruit?
Engineer die de knoop doorhakte
1–2 pagina's
Googles richtlijnen beschrijven het design doc als de plek om de implementatiestrategie op hoofdlijnen en de belangrijkste ontwerpbeslissingen vast te leggen, met nadruk op de afwegingen. Michael Nygards ADR-formaat uit 2011 versmalt dat tot één beslissing met vijf onderdelen: titel, context, beslissing, status en gevolgen (Michael Nygard, 2011). Wil je eerst de productkant, begin dan met de gids voor het schrijven van een PRD.
Waarom slaan engineers de meeste technische specs over?
Engineers slaan specs over die vragen beantwoorden die niemand stelde en de vragen die ertoe doen verstoppen. Drie patronen verklaren het meeste.
Ze zijn geschreven voor volledigheid, niet voor beslissingen. Jakob Nielsens analyse uit 2008 vond dat lezers op een gemiddelde pagina van 593 woorden tijd hadden voor hooguit 28% van de woorden, en dat 20% waarschijnlijker was. Alleen bij pagina's van 111 woorden of minder kwamen lezers door de helft van de inhoud heen. Een reviewer met zes specs in de wachtrij leest op dezelfde manier: samenvatting, diagram, vetgedrukte tekst, en dan het onderdeel waar hij het niet mee eens is.
Ze verstoppen de riskante keuze in vlakke tekst. Staat de onomkeerbare beslissing in alinea negen, dan moet elke reviewer hem zelf opnieuw afleiden. Dat is precies de verspilling die een spec moet voorkomen.
Ze raken verouderd. De Stack Overflow Developer Survey 2024 vond dat 61% van de respondenten meer dan 30 minuten per dag zoekt naar antwoorden, en dat 30% zegt dat kennissilo's hun productiviteit 10 keer per week of vaker schaden. Een spec die niet meer bij de code past, wordt weer een bron van verkeerde antwoorden.
De winst van het goed doen is meetbaar. DORA's onderzoek uit 2021 toonde dat teams met goede documentatie 3,8 keer zo vaak security best practices toepasten en 2,5 keer zo vaak de cloud ten volle benutten.
Wat hoort er in een technische spec?
Neem alleen op wat verandert hoe iemand het werk zou bouwen of beoordelen. Twee gepubliceerde praktijken geven een goede basis.
De onderdelen van Googles design doc
Malte Ubls beschrijving uit 2020 van design docs bij Google noemt de onderdelen die de meeste docs gemeen hebben:
Context en scope: de omgeving waarin het systeem leeft, in een paar alinea's.
Doelen en niet-doelen: wat het systeem moet doen, en wat het uitdrukkelijk niet doet.
Het eigenlijke ontwerp: systeemdiagram, API's, gegevensopslag, en code of pseudocode alleen waar die een nieuw algoritme verduidelijkt.
Overwogen alternatieven: andere ontwerpen en waarom ze verloren.
Cross-cutting concerns: security, privacy en observability.
De onderdelen van Ubers RFC's
Ubers RFC-proces groeide mee met het bedrijf, van tientallen engineers naar een paar duizend, volgens Gergely Orosz, die er werkte (The Pragmatic Engineer, 2018). De backend-template begon met een lijst van goedkeurders en behandelde daarna architectuurwijzigingen, service-SLA's, afhankelijkheden, load testing, multi-datacenteraspecten, security, testen en uitrol, metrics en monitoring, en klantenondersteuning. De mobiele template voegde UI en toegankelijkheid toe. Onderdelen kwamen erbij naarmate het bedrijf leerde wat het steeds over het hoofd zag.
De les uit beide: een technische spec-template is een checklist van eerdere fouten. Begin klein en voeg pas een onderdeel toe als het ontbreken ervan een echt probleem heeft veroorzaakt.
Technische spec-template (kopiëren en aanpassen)
Deze technische spec-template combineert Googles onderdelen, Ubers gewoonte om goedkeurders vooraan te zetten en Nygards beslissingsformaat. Verwijder elk onderdeel waar alleen „n.v.t.” zou staan.
# [Naam van feature of systeem]: technische spec
**Samenvatting:** We doen [X] om [Y] te bereiken, en accepteren daarbij de afweging [Z].
**Auteur:** [naam] · **Goedkeurders:** [2–3 namen] · **Review voor:** [datum]
**Status:** Concept | In review | Goedgekeurd | Vervangen door [link]
**Gekoppeld PRD / ticket:** [link]
## 1. Probleem en randvoorwaarden
- Wat is er kapot, wie merkt het, en wat wordt mogelijk als het is opgelost.
- Harde randvoorwaarden: latencybudget, dataresidentie, achterwaartse
compatibiliteit, de SLA die je niet mag breken.
## 2. Doelen en niet-doelen
- Doelen (waar mogelijk meetbaar).
- Niet-doelen: dingen die een redelijke lezer zou verwachten en die we niet doen.
## 3. Belangrijkste beslissingen (lees dit eerst)
| # | Beslissing | Omkeerbaar? | Risico als het fout is | Vertrouwen |
|---|----------|-------------|---------------|------------|
| 1 | | Eenrichtingsdeur / tweerichtingsdeur | | Hoog / Midden / Laag |
## 4. Voorgesteld ontwerp
- Eén diagram. API- en datamodelwijzigingen. Pseudocode alleen voor
alles wat nieuw is.
## 5. Overwogen alternatieven
- Optie A: waarom die verloor.
- Optie B: waarom die verloor.
- Niets doen: wat gebeurt er als we dit niet bouwen.
## 6. Risico's en open vragen
- Dragende aannames en hoe we die gaan toetsen.
- Vragen die we vóór of tijdens het bouwen beantwoord moeten hebben.
## 7. Cross-cutting concerns
- Security en privacy · Observability · Toegankelijkheid · Kosten.
## 8. Uitrol, validatie en rollback
- Feature flag / gefaseerde uitrol.
- Metrics die bewijzen dat het werkt, en de drempel die een rollback activeert.
## 9. Beslissingslog
- [datum] [Beslissing] gewijzigd omdat [reden]. (Werk het hier bij, niet in een PR-comment.)
De beslissingstabel in onderdeel 3 is het deel dat de template zijn waarde geeft. Door elke beslissing als eenrichtings- of tweerichtingsdeur te markeren, zien reviewers waar ze hun aandacht moeten richten. Het raamwerk voor omkeerbare en onomkeerbare beslissingen legt uit hoe je beoordeelt wat wat is.
Hoe lang moet een technische spec zijn?
Zo kort als de riskantste beslissing toelaat. Googles richtlijnen schatten design docs voor grote projecten op ongeveer 10 tot 20 pagina's en vinden „mini design docs” van 1 tot 3 pagina's prima voor incrementeel werk. Nygards ADR's zijn één of twee pagina's. Amazon vervangt slides door „verhalend opgebouwde memo's van zes pagina's” die aan het begin van elke meeting in stilte worden gelezen, en Jeff Bezos schreef dat een goede er waarschijnlijk een week of langer over doet om te schrijven (Amazon, 2018).
Een praktische vuistregel, naar omvang van de wijziging:
Wijziging
Formaat
Lengte
Review
Bugfix, tekstwijziging, configuratieaanpassing
Ticketbeschrijving
Een alinea
Alleen code review
Nieuw endpoint of component binnen één service
Mini-spec
1 pagina
Eén goedkeurder, asynchroon
Feature die 2–3 services of een publieke API raakt
Technische spec (template hierboven)
2–3 pagina's
2–3 goedkeurders, venster van 2–3 dagen
Nieuw systeem, datamigratie of beveiligingsgrens
Volledig design doc of RFC
5–20 pagina's
Formele reviewmeeting
Googles richtlijnen zeggen ook wanneer je er géén schrijft: als de oplossing ondubbelzinnig is en het document slechts een implementatiehandleiding zou zijn zonder afwegingen om te bespreken.
Hoe schrijf je een spec die engineers echt lezen?
Schrijf hem in deze volgorde. Het meeste werk is bepalen wat je weglaat.
Schrijf eerst de samenvatting in één zin. „We doen X om Y te bereiken, en accepteren daarbij de afweging Z.” Lukt dat niet, dan ben je nog niet klaar om de spec te schrijven, en je reviewers kunnen hem dan ook niet samenvatten.
Open met het probleem, niet met de oplossing. Engineers kunnen een ontwerp pas beoordelen als ze de randvoorwaarden kennen waaraan het moet voldoen. Noem de onderhandelbare punten vóór het architectuurdiagram.
Vul de beslissingstabel in. Noem elke beslissing waar een reviewer het redelijkerwijs mee oneens kan zijn. Maak de eenrichtingsdeuren vet.
Schrijf de alternatieven eerlijk op. Neem „niets doen” mee. Een spec zonder afgewezen opties leest als een beslissing die al genomen is.
Noem twee of drie goedkeurders en een reviewdeadline. Uber zette de goedkeurders bovenaan elke RFC. Een spec zonder beslisser en datum blijft vaak eindeloos in review hangen.
Review asynchroon, kom alleen samen bij meningsverschillen. Comments in het document vangen het meeste feedback op. Kom je wel samen, doe dan als Amazon en besteed de eerste tien minuten aan stil lezen.
Werk de spec bij als de bouw hem verandert. In Googles levenscyclus wordt het document tijdens de implementatie herzien. Leg wijzigingen vast in het beslissingslog, niet in een pull-requestcomment die niemand terugvindt.
Orosz merkt op dat het opschrijven meestal een paar uur kost zodra een team het over een plan eens is. Kost het dagen, dan is het meningsverschil de eigenlijke bevinding.
Uitgewerkt voorbeeld (ter illustratie)
Stel dat een team van zes mensen moet voorkomen dat trage webhooks van klanten de checkout laten time-outen. Hun samenvattingszin: „We verplaatsen webhook-bezorging naar een queue zodat de checkout nooit wacht op de server van een klant, en accepteren daarbij tot 60 seconden bezorgvertraging.”
#
Beslissing
Omkeerbaar?
Risico als het fout is
Vertrouwen
1
Overstappen op at-least-once-bezorging; klanten moeten ontdubbelen op event-ID
Eenrichtingsdeur (publiek contract)
Dubbele bestellingen in systemen van klanten
Midden
2
De bestaande Postgres-database als queue gebruiken in plaats van een nieuwe broker
Tweerichtingsdeur
Doorvoerplafond bij piekbelasting; later migreren
Hoog
3
Vijf keer opnieuw proberen over 24 uur, daarna als mislukt markeren
Tweerichtingsdeur
Sommige klanten missen events bij lange storingen
Hoog
Reviewers zien in 30 seconden dat beslissing 1 het debat verdient: ze wijzigt een publiek API-contract, vraagt om een migratienotitie voor klanten en kan niet ongemerkt worden teruggedraaid. De beslissingen 2 en 3 kunnen in een comment worden goedgekeurd.
Wat zijn veelgemaakte fouten bij technische specs?
De spec na de code schrijven. Een spec die een afgeronde pull request moet rechtvaardigen, heeft geen alternatieven en vangt niets op.
Vijf diagrammen in plaats van één. Eén systeemdiagram met de wijziging gemarkeerd wint van vijf die alles tonen.
De template als formulier behandelen. Lege „n.v.t.”-onderdelen leren lezers om te scannen. Verwijder ze.
Geen eigenaar voor open vragen. Elke open vraag heeft een naam en een datum nodig, anders wordt het een productie-incident.
Het document bevriezen. Een spec die niet meer bij de bouw past, is erger dan geen spec, omdat mensen hem vertrouwen.
Een spec gebruiken waar een prototype sneller antwoord geeft. Als de riskante vraag is „kan deze library onze load aan?”, wint een spike van een dag van vijf pagina's betoog.
Hoe veranderen technische specs met AI-codeeragents?
Codeeragents lezen specs letterlijk. Onduidelijkheid die een menselijke engineer in Slack zou oplossen, wordt code die een agent met overtuiging verkeerd schrijft. De onderdelen van de template die het meest tellen voor een agent zijn de niet-doelen, de randvoorwaarden en toetsbare acceptatiecriteria. De PRD-template voor AI-codeeragents laat zien hoe je die expliciet maakt. Zodra de spec is goedgekeurd, is het PRD opknippen in user stories de volgende stap, en een pre-mortem voor de lancering test het uitrolplan op stevigheid vóór de release.
Waar past Specky?
De kloof tussen gedocumenteerde intentie en opgeleverde werkelijkheid ontstaat meestal als requirements, beslissingen en tickets in verschillende tools staan. Specky schrijft PRD's in een editor met inline bronvermeldingen naar het klantbewijs, genereert tickets met toetsbare acceptatiecriteria en legt beslissingen vast in een Product Graph, zodat het „waarom” aan het werk blijft hangen. Codeeragents kunnen die context lezen via een MCP-server. De engineer schrijft nog steeds het technische ontwerp; de productcontext eromheen blijft actueel. Als tijd vinden om te schrijven het knelpunt is, beschermt de voorbeeldweek van een PM daar een focusblok voor.
Veelgestelde vragen
Wat is het verschil tussen een PRD en een technische spec?
Een PRD definieert het probleem, de gebruikers en hoe succes wordt gemeten; een technische spec definieert hoe het team de oplossing bouwt en welke afwegingen het accepteert. De product manager is meestal eigenaar van het PRD en de tech lead van de spec. Schrijf eerst het PRD en link ernaar vanuit de spec, zodat reviewers het ontwerp aan het oorspronkelijke doel kunnen toetsen.
Wie moet de technische spec schrijven?
De engineer of tech lead die de bouw gaat dragen, moet de technische spec schrijven, en de product manager beoordeelt hem tegen het PRD. De auteur is verantwoordelijk voor de beslissingen, niet voor het intypen van elk onderdeel. In een klein team kan de PM de onderdelen probleem, doelen en niet-doelen opzetten, en maakt de engineer ontwerp, alternatieven en uitrolplan af.
Hoe lang moet een technisch ontwerpdocument zijn?
De meeste technische ontwerpdocumenten horen één tot drie pagina's te zijn. In Googles praktijk zijn mini design docs van 1 tot 3 pagina's gewoon voor incrementele wijzigingen en zijn 10 tot 20 pagina's bedoeld voor grote nieuwe systemen. Is je spec voor een feature binnen bestaande services langer dan drie pagina's, dan bevat hij waarschijnlijk meerdere beslissingen die aparte ADR's zouden moeten zijn.
Wat is een RFC in software engineering?
Een RFC (request for comments) is een schriftelijk plan dat vóór de start van het werk met de bredere engineeringorganisatie wordt gedeeld, zodat anderen risico's kunnen aankaarten. Uber gebruikte RFC's terwijl het groeide van tientallen naar een paar duizend engineers, met bovenaan elke RFC de goedkeurders bij naam. Een RFC is een technische spec plus een reviewproces, een deadline en een beslisser.
Wanneer moet je geen technische spec schrijven?
Sla de spec over als de oplossing ondubbelzinnig is en er geen betekenisvolle afwegingen te bespreken zijn, wat de grens is die Googles richtlijnen trekken. Bugfixes, kleine UI-wijzigingen en configuratie-updates horen in een ticket. Is de grootste onzekerheid de technische haalbaarheid, doe dan eerst een tijdgebonden spike en schrijf de spec zodra je weet wat werkt.
Wat is een architecture decision record (ADR)?
Een ADR is een vastlegging van één of twee pagina's van één enkele architectuurbeslissing. Michael Nygards formaat uit 2011 heeft vijf onderdelen: titel, context, beslissing, status en gevolgen. Veel teams bewaren ADR's in de coderepository, zodat toekomstige engineers zien waarom iets op een bepaalde manier is gebouwd. Gebruik ADR's voor beslissingen die langer meegaan dan één spec.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing