17. Juni 2026Aktualisiert am Fathy Shalaby13 Min. Lesezeit
Technical-Spec-Vorlage: So schreibst du eine Spec, die Entwickler wirklich lesen
Eine kopierbare Technical-Spec-Vorlage, die Design-Doc- und RFC-Praktiken, von denen sie sich einiges abschaut, und eine Schritt-für-Schritt-Methode für eine Spec, die Entwickler bis zum Ende lesen.
Teilen
Dieser Artikel wurde aus dem Englischen übersetzt. Original lesen
Eine Technical-Spec-Vorlage sollte die riskanten Entscheidungen auf Seite eins stellen: das Problem samt Randbedingungen, den Designvorschlag, die verworfenen Alternativen und das, was schiefgehen kann – bei den meisten Änderungen auf ein bis drei Seiten. Google-Design-Docs und Uber-RFCs folgen dieser Form. Die kopierbare Vorlage unten ergänzt einen Ein-Satz-Überblick und eine Entscheidungstabelle, damit Reviewer die schwierigen Entscheidungen in unter einer Minute finden.
Das Wichtigste in Kürze
Googles Design-Docs haben fünf Kernabschnitte und umfassen bei großen Projekten 10 bis 20 Seiten, bei inkrementeller Arbeit dagegen 1 bis 3 Seiten (Malte Ubl, 2020).
Leser nehmen auf einer durchschnittlichen Webseite etwa 20 % der Wörter auf, höchstens 28 % (Nielsen Norman Group, 2008). Specs werden genauso gelesen: Man überfliegt sie nach den Stellen, die falsch sein könnten.
61 % der Entwickler verbringen täglich mehr als 30 Minuten damit, nach Antworten zu suchen (Stack Overflow, 2024). Eine Spec, die Entscheidungen festhält, beantwortet diese Fragen ein einziges Mal.
Teams mit hochwertiger Dokumentation setzen Security-Best-Practices 3,8-mal wahrscheinlicher um (DORA, 2021).
„Betrachtete Alternativen“ ist der Abschnitt, dem Reviewer am meisten vertrauen, weil er zeigt, dass du nach einem Grund gesucht hast, es nicht so zu bauen.
Was ist eine Technical Spec, und wie unterscheidet sie sich von einem PRD?
Eine Technical Spec (auch Design-Doc oder technisches Designdokument) erklärt, wie ein Team etwas bauen wird und welche Kompromisse es dabei eingeht. Ein PRD erklärt, welches Problem es wert ist, gelöst zu werden, für wen und woran man den Erfolg misst. Das PRD kommt zuerst, die Technical Spec antwortet darauf.
Teams nutzen vier verwandte Dokumente. Sie zu vermischen ist der häufigste Grund, warum eine Spec auf 15 Seiten anwächst, die niemand zu Ende liest.
Welches Problem, für wen, und woran erkennen wir, dass es funktioniert hat?
Product Manager
2–5 Seiten
Technical Spec / Design-Doc
Wie bauen wir es, und welche Kompromisse gehen wir ein?
Tech Lead oder Entwickler
1–3 Seiten (10–20 bei großen Systemen)
RFC (Request for Comments)
Stimmt die übrige Organisation diesem Plan zu, bevor die Arbeit beginnt?
Autor plus benannte Freigeber
Wie eine Spec, mit Review-Frist
ADR (Architecture Decision Record)
Warum haben wir genau diese eine Entscheidung getroffen, und was folgt daraus?
Entwickler, der die Entscheidung getroffen hat
1–2 Seiten
Googles Leitfaden beschreibt das Design-Doc als den Ort, an dem die übergeordnete Umsetzungsstrategie und die wichtigsten Designentscheidungen dokumentiert werden – mit Schwerpunkt auf den Kompromissen. Michael Nygards 2011 veröffentlichtes ADR-Format engt das auf eine einzelne Entscheidung mit fünf Teilen ein: Titel, Kontext, Entscheidung, Status und Konsequenzen (Michael Nygard, 2011). Wenn du zuerst die Produktseite klären willst, beginne mit dem Leitfaden zum Schreiben eines PRD.
Warum überspringen Entwickler die meisten Technical Specs?
Entwickler überspringen Specs, die Fragen beantworten, die niemand gestellt hat, und die wichtigen Fragen verstecken. Drei Muster erklären das meiste.
Sie sind auf Vollständigkeit geschrieben, nicht auf Entscheidungen. Jakob Nielsens Analyse von 2008 ergab: Auf einer durchschnittlichen Seite mit 593 Wörtern hatten Leser Zeit für höchstens 28 % der Wörter, wahrscheinlicher waren 20 %. Nur bei Seiten mit 111 Wörtern oder weniger kamen Leser durch die Hälfte des Inhalts. Ein Reviewer mit sechs Specs in der Warteschlange liest genauso: Zusammenfassung, Diagramm, Fettgedrucktes, dann der Abschnitt, mit dem er nicht einverstanden ist.
Sie verstecken die riskante Entscheidung in Fließtext. Steht die unumkehrbare Entscheidung in Absatz neun, muss jeder Reviewer sie neu herleiten. Genau diese Verschwendung soll eine Spec verhindern.
Sie veralten. Der Stack Overflow Developer Survey 2024 fand: 61 % der Befragten verbringen täglich mehr als 30 Minuten mit der Suche nach Antworten, und 30 % sagen, Wissenssilos schadeten ihrer Produktivität zehnmal oder öfter pro Woche. Eine Spec, die nicht mehr zum Code passt, wird zu einer weiteren Quelle falscher Antworten.
Der Gewinn, wenn man es richtig macht, ist messbar. DORAs Forschung von 2021 zeigte: Teams mit hochwertiger Dokumentation setzten Security-Best-Practices 3,8-mal wahrscheinlicher um und nutzten die Cloud 2,5-mal wahrscheinlicher voll aus.
Was gehört in eine Technical Spec?
Nimm nur auf, was verändert, wie jemand die Arbeit bauen oder prüfen würde. Zwei veröffentlichte Praktiken liefern eine gute Grundlage.
Die Abschnitte von Googles Design-Doc
Malte Ubls Beschreibung der Design-Docs bei Google aus dem Jahr 2020 nennt die Abschnitte, die die meisten Docs gemeinsam haben:
Kontext und Umfang: das Umfeld, in dem das System lebt, in wenigen Absätzen.
Ziele und Nicht-Ziele: was das System leisten muss und was es ausdrücklich nicht leistet.
Das eigentliche Design: Systemdiagramm, APIs, Datenspeicherung, und Code oder Pseudocode nur dort, wo er einen neuartigen Algorithmus erklärt.
Betrachtete Alternativen: andere Designs und warum sie verloren haben.
Übergreifende Themen: Sicherheit, Datenschutz und Observability.
Die Abschnitte von Ubers RFCs
Ubers RFC-Prozess wuchs mit dem Unternehmen von einigen Dutzend auf ein paar tausend Entwickler, so Gergely Orosz, der dort gearbeitet hat (The Pragmatic Engineer, 2018). Die Backend-Vorlage begann mit einer Liste der Freigeber und behandelte dann Architekturänderungen, Service-SLAs, Abhängigkeiten, Lasttests, Multi-Rechenzentrums-Themen, Sicherheit, Tests und Rollout, Metriken und Monitoring sowie Kundensupport. Die Mobile-Vorlage ergänzte UI und Barrierefreiheit. Abschnitte kamen hinzu, wenn das Unternehmen merkte, was es immer wieder übersah.
Die Lehre aus beiden: Eine Technical-Spec-Vorlage ist eine Checkliste vergangener Fehler. Fang klein an und füge einen Abschnitt erst hinzu, wenn sein Fehlen ein echtes Problem verursacht hat.
Technical-Spec-Vorlage (kopieren und anpassen)
Diese Technical-Spec-Vorlage verbindet Googles Abschnitte, Ubers Gewohnheit, Freigeber an den Anfang zu stellen, und Nygards Entscheidungsformat. Lösche jeden Abschnitt, der nur „entfällt“ sagen würde.
# [Name des Features oder Systems]: Technical Spec
**Zusammenfassung:** Wir machen [X], um [Y] zu erreichen, und nehmen dafür [Z] in Kauf.
**Autor:** [Name] · **Freigeber:** [2–3 Namen] · **Review bis:** [Datum]
**Status:** Entwurf | Im Review | Freigegeben | Ersetzt durch [Link]
**Verknüpftes PRD / Ticket:** [Link]
## 1. Problem und Randbedingungen
- Was ist kaputt, wer spürt es, und was wird möglich, wenn es behoben ist.
- Harte Randbedingungen: Latenzbudget, Datenresidenz, Abwärts-
kompatibilität, die SLA, die du nicht brechen darfst.
## 2. Ziele und Nicht-Ziele
- Ziele (wo möglich messbar).
- Nicht-Ziele: Dinge, die ein vernünftiger Leser erwarten könnte und die wir nicht tun.
## 3. Zentrale Entscheidungen (zuerst lesen)
| # | Entscheidung | Umkehrbar? | Risiko, falls falsch | Konfidenz |
|---|----------|-------------|---------------|------------|
| 1 | | Einbahn- / Zweiwegetür | | Hoch / Mittel / Niedrig |
## 4. Vorgeschlagenes Design
- Ein Diagramm. API- und Datenmodelländerungen. Pseudocode nur für
alles Neuartige.
## 5. Betrachtete Alternativen
- Option A: warum sie verloren hat.
- Option B: warum sie verloren hat.
- Nichts tun: was passiert, wenn wir das nicht bauen.
## 6. Risiken und offene Fragen
- Tragende Annahmen und wie wir sie prüfen.
- Fragen, die vor oder während des Baus beantwortet sein müssen.
## 7. Übergreifende Themen
- Sicherheit und Datenschutz · Observability · Barrierefreiheit · Kosten.
## 8. Rollout, Validierung und Rollback
- Feature Flag / gestufter Rollout.
- Metriken, die belegen, dass es funktioniert, und der Schwellenwert, der ein Rollback auslöst.
## 9. Entscheidungslog
- [Datum] [Entscheidung] geändert, weil [Grund]. (Hier aktualisieren, nicht in einem PR-Kommentar.)
Die Entscheidungstabelle in Abschnitt 3 ist der Teil, der der Vorlage ihren Wert gibt. Wenn du jede Entscheidung als Einbahn- oder Zweiwegetür markierst, wissen Reviewer, wo sie ihre Aufmerksamkeit einsetzen sollen. Das Framework für umkehrbare und unumkehrbare Entscheidungen erklärt, wie du beurteilst, was was ist.
Wie lang sollte eine Technical Spec sein?
So kurz, wie die riskanteste Entscheidung es erlaubt. Googles Leitfaden sieht für Design-Docs großer Projekte etwa 10 bis 20 Seiten vor und hält 1- bis 3-seitige „Mini-Design-Docs“ für inkrementelle Arbeit für völlig in Ordnung. Nygards ADRs umfassen ein bis zwei Seiten. Amazon ersetzt Folien durch „narrativ aufgebaute Sechs-Seiten-Memos“, die zu Beginn jedes Meetings still gelesen werden, und Jeff Bezos schrieb, dass ein wirklich gutes wahrscheinlich eine Woche oder länger zum Schreiben braucht (Amazon, 2018).
Eine praktische Faustregel nach Größe der Änderung:
Änderung
Format
Länge
Review
Bugfix, Textänderung, Konfigurationsanpassung
Ticketbeschreibung
Ein Absatz
Nur Code-Review
Neuer Endpoint oder neue Komponente innerhalb eines Services
Mini-Spec
1 Seite
Ein Freigeber, asynchron
Feature, das 2–3 Services oder eine öffentliche API berührt
Technical Spec (Vorlage oben)
2–3 Seiten
2–3 Freigeber, 2–3 Tage Zeitfenster
Neues System, Datenmigration oder Sicherheitsgrenze
Vollständiges Design-Doc oder RFC
5–20 Seiten
Formelles Review-Meeting
Googles Leitfaden sagt auch, wann man keine schreiben sollte: wenn die Lösung eindeutig ist und das Dokument nur eine Implementierungsanleitung ohne Kompromisse zum Diskutieren wäre.
Wie schreibst du eine Spec, die Entwickler wirklich lesen?
Schreibe sie in dieser Reihenfolge. Der größte Teil der Arbeit besteht darin, zu entscheiden, was du weglässt.
Schreib zuerst den Ein-Satz-Überblick. „Wir machen X, um Y zu erreichen, und nehmen dafür Z in Kauf.“ Wenn du ihn nicht schreiben kannst, bist du noch nicht bereit für die Spec, und deine Reviewer werden sie auch nicht zusammenfassen können.
Beginne mit dem Problem, nicht mit der Lösung. Entwickler können ein Design erst beurteilen, wenn sie die Randbedingungen kennen, denen es dient. Nenne die nicht verhandelbaren Punkte vor dem Architekturdiagramm.
Fülle die Entscheidungstabelle aus. Liste jede Entscheidung auf, der ein Reviewer vernünftigerweise widersprechen könnte. Hebe die Einbahnstraßen fett hervor.
Schreibe die Alternativen ehrlich. Nimm „Nichts tun“ auf. Eine Spec ohne verworfene Optionen liest sich wie eine bereits gefallene Entscheidung.
Nenne zwei oder drei Freigeber und eine Review-Frist. Uber führte oben in jedem RFC die Freigeber auf. Eine Spec ohne Entscheider und Datum bleibt tendenziell unbegrenzt im Review hängen.
Reviewe asynchron, triff dich nur bei Meinungsverschiedenheiten. Kommentare im Dokument erledigen das meiste Feedback. Wenn ihr euch trefft, macht es wie Amazon und gebt die ersten zehn Minuten dem stillen Lesen.
Aktualisiere die Spec, wenn der Bau sie verändert. In Googles Lebenszyklus wird das Dokument während der Umsetzung überarbeitet. Halte Änderungen im Entscheidungslog fest, nicht in einem Pull-Request-Kommentar, den niemand findet.
Orosz weist darauf hin: Sobald sich ein Team auf einen Plan geeinigt hat, dauert das Aufschreiben meist ein paar Stunden. Dauert es Tage, ist die Uneinigkeit das eigentliche Ergebnis.
Durchgespieltes Beispiel (zur Veranschaulichung)
Angenommen, ein Team aus sechs Leuten muss verhindern, dass langsame Kunden-Webhooks den Checkout in Timeouts treiben. Ihr Überblickssatz: „Wir verlagern die Webhook-Zustellung auf eine Queue, damit der Checkout nie auf den Server eines Kunden wartet, und nehmen dafür bis zu 60 Sekunden Zustellverzögerung in Kauf.“
#
Entscheidung
Umkehrbar?
Risiko, falls falsch
Konfidenz
1
Auf At-least-once-Zustellung umstellen; Kunden müssen per Event-ID deduplizieren
Einbahnstraße (öffentlicher Vertrag)
Doppelte Bestellungen in Kundensystemen
Mittel
2
Die bestehende Postgres-Datenbank als Queue nutzen statt eines neuen Brokers
Zweiwegetür
Durchsatzgrenze bei Spitzenlast; später migrieren
Hoch
3
Fünf Wiederholungen über 24 Stunden, danach als fehlgeschlagen markieren
Zweiwegetür
Manche Kunden verpassen bei langen Ausfällen Events
Hoch
Reviewer sehen in 30 Sekunden, dass Entscheidung 1 die Debatte verdient: Sie ändert einen öffentlichen API-Vertrag, braucht einen Migrationshinweis für Kunden und lässt sich nicht stillschweigend zurücknehmen. Die Entscheidungen 2 und 3 lassen sich per Kommentar freigeben.
Was sind die häufigsten Fehler bei Technical Specs?
Die Spec nach dem Code schreiben. Eine Spec, die einen fertigen Pull Request rechtfertigen soll, hat keine Alternativen und fängt nichts ab.
Fünf Diagramme statt einem. Ein Systemdiagramm mit hervorgehobener Änderung schlägt fünf, die alles zeigen.
Die Vorlage wie ein Formular behandeln. Leere „entfällt“-Abschnitte bringen Lesern bei, nur zu überfliegen. Lösche sie.
Kein Owner für offene Fragen. Jede offene Frage braucht einen Namen und ein Datum, sonst wird sie zu einem Produktionsvorfall.
Das Dokument einfrieren. Eine Spec, die nicht mehr zum Bau passt, ist schlimmer als keine, weil Leute ihr vertrauen.
Eine Spec schreiben, wo ein Prototyp schneller antwortet. Wenn die riskante Frage lautet „Hält diese Bibliothek unsere Last aus?“, schlägt ein eintägiger Spike ein fünfseitiges Argument.
Wie verändern KI-Coding-Agenten Technical Specs?
Coding-Agenten lesen Specs wörtlich. Eine Unschärfe, die ein menschlicher Entwickler in Slack klärt, wird zu Code, den ein Agent selbstsicher falsch schreibt. Für einen Agenten sind die wichtigsten Teile der Vorlage die Nicht-Ziele, die Randbedingungen und testbare Akzeptanzkriterien. Die PRD-Vorlage für KI-Coding-Agenten zeigt, wie du sie explizit machst. Sobald die Spec freigegeben ist, ist das Aufteilen des PRD in User Stories der nächste Schritt, und eine Launch-Pre-Mortem testet den Rollout-Plan vor dem Release auf Belastbarkeit.
Wo passt Specky ins Bild?
Die Lücke zwischen dokumentierter Absicht und ausgelieferter Realität entsteht meist dann, wenn Anforderungen, Entscheidungen und Tickets in verschiedenen Tools liegen. Specky entwirft PRDs in einem Editor mit Inline-Zitaten, die auf die Kundenbelege zurückführen, erzeugt Tickets mit testbaren Akzeptanzkriterien und hält Entscheidungen in einem Product Graph fest, damit das „Warum“ an der Arbeit hängen bleibt. Coding-Agenten können diesen Kontext über einen MCP-Server lesen. Das technische Design schreibt weiterhin der Entwickler; der Produktkontext drumherum bleibt aktuell. Wenn die Zeit zum Schreiben der Engpass ist, schützt der Beispiel-Wochenplan für Product Manager einen Fokusblock dafür.
Häufig gestellte Fragen
Was ist der Unterschied zwischen einem PRD und einer Technical Spec?
Ein PRD definiert das Problem, die Nutzer und die Erfolgsmessung; eine Technical Spec definiert, wie das Team die Lösung baut und welche Kompromisse es eingeht. Das PRD gehört meist dem Product Manager, die Spec dem Tech Lead. Schreib zuerst das PRD und verlinke es dann aus der Spec, damit Reviewer das Design am ursprünglichen Ziel prüfen können.
Wer sollte die Technical Spec schreiben?
Der Entwickler oder Tech Lead, der den Bau verantwortet, sollte die Technical Spec schreiben, und der Product Manager prüft sie gegen das PRD. Der Autor ist für die Entscheidungen verantwortlich, nicht dafür, jeden Abschnitt selbst zu tippen. In einem kleinen Team kann der PM die Abschnitte Problem, Ziele und Nicht-Ziele entwerfen, und der Entwickler ergänzt Design, Alternativen und Rollout-Plan.
Wie lang sollte ein technisches Designdokument sein?
Die meisten technischen Designdokumente sollten ein bis drei Seiten lang sein. In Googles Praxis gelten 1- bis 3-seitige Mini-Design-Docs für inkrementelle Änderungen als normal, 10 bis 20 Seiten sind großen neuen Systemen vorbehalten. Wenn deine Spec für ein Feature innerhalb bestehender Services länger als drei Seiten wird, vermischt sie wahrscheinlich mehrere Entscheidungen, die getrennte ADRs sein sollten.
Was ist ein RFC in der Softwareentwicklung?
Ein RFC (Request for Comments) ist ein schriftlicher Plan, der vor Arbeitsbeginn mit der gesamten Engineering-Organisation geteilt wird, damit andere Risiken aufzeigen können. Uber setzte RFCs ein, als es von einigen Dutzend auf ein paar tausend Entwickler wuchs, und führte oben in jedem RFC namentlich die Freigeber auf. Ein RFC ist eine Technical Spec plus Review-Prozess, Frist und Entscheider.
Wann sollte man keine Technical Spec schreiben?
Verzichte auf die Spec, wenn die Lösung eindeutig ist und es keine nennenswerten Kompromisse zu diskutieren gibt – genau diese Grenze zieht Googles Leitfaden. Bugfixes, kleine UI-Änderungen und Konfigurationsupdates gehören in ein Ticket. Liegt die Hauptunsicherheit in der technischen Machbarkeit, mach zuerst einen zeitlich begrenzten Spike und schreib die Spec, sobald du weißt, was funktioniert.
Was ist ein Architecture Decision Record (ADR)?
Ein ADR ist eine ein- bis zweiseitige Aufzeichnung einer einzelnen Architekturentscheidung. Michael Nygards Format von 2011 hat fünf Teile: Titel, Kontext, Entscheidung, Status und Konsequenzen. Viele Teams legen ADRs im Code-Repository ab, damit künftige Entwickler sehen, warum etwas so gebaut wurde. Nutze ADRs für Entscheidungen, die länger leben als eine einzelne 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