# Vorlage für ein technisches Designdokument

Sechs verlinkte Dokumente, die ein System von den Anforderungen bis zum Rollout begleiten: der Kontext, die Architektur, Daten und Schnittstellen, wie es läuft und wie es ausfällt, und die verworfenen Optionen. Laden Sie sie als Markdown-Dateien herunter: Sie öffnen sich in jedem Editor, liegen im Repository neben dem Code, zeichnen ihre Diagramme auf GitHub und in Obsidian und lassen sich als Karte in Nodary importieren.

Kostenlos, ohne Konto und ohne E-Mail-Adresse. Nutzen, ändern und teilen Sie sie, wie Sie möchten.

[Vorlage herunterladen (.zip)](https://nodary.ai/downloads/vorlage-technisches-designdokument.zip)

## Lesen Sie jede Seite vor dem Download

Die Übersicht passt auf einen Bildschirm und verlinkt fünf Teile: Ein Reviewer liest die Zusammenfassung und geht dann direkt zu dem Teil, der ihn betrifft. Kursive Zeilen sagen, was hineingehört; die Beispiele folgen einem Beispiel-Feature, Freigabelinks, die ablaufen.

- Technisches Designdokument: Die Seite, die alle zuerst lesen: die Zusammenfassung, Ziele und Nicht-Ziele und ein Link zu jedem Teil.
- Kontext und Anforderungen: Der Ist-Zustand, die Anforderungen, die das Design erfüllen muss, und die Rahmenbedingungen.
- Architektur: Die Komponenten, wie sie miteinander sprechen, wie eine Anfrage sie durchläuft, und die Schlüsselentscheidungen.
- Daten und Schnittstellen: Das Datenmodell, die APIs und Events und wie vorhandene Daten in die neue Form kommen.
- Betrieb: Wie es ausgeliefert und überwacht wird, wie es sicher bleibt, und was passiert, wenn etwas ausfällt.
- Alternativen und Risiken: Die verworfenen Optionen und warum, die Risiken, der Rollout-Plan und die offenen Fragen.

### Technisches Designdokument

_So nutzen Sie diese Vorlage: Kursive Zeilen sind Hinweise. Ersetzen Sie sie durch Ihre eigenen Worte und löschen Sie sie dann. Werte in eckigen Klammern füllen Sie aus. Halten Sie diese Seite auf einem Bildschirm: Ein Reviewer soll daran erkennen, was er freigibt._

#### Auf einen Blick

| Feld | Dieses Design |
| --- | --- |
| System oder Feature | [Name] |
| Autor | [Name] |
| Reviewer | [Namen] |
| Status | [Entwurf, in Prüfung, freigegeben, umgesetzt] |
| Anforderungen | [Link zum PRD] |
| Ziel-Release | [Datum oder Version] |

#### Zusammenfassung

_Drei Sätze: was Sie bauen, warum und die eine Entscheidung, die ein Reviewer zuerst ansehen sollte._

_Beispiel (ein Beispiel-Feature): Freigabelinks bekommen ein optionales Enddatum. Jede Anfrage prüft das Datum, also funktioniert ein Link ab seinem Ende nicht mehr. Ein geplanter Job widerruft abgelaufene Links jede Minute; er räumt nur auf, ein verspäteter Lauf ändert für die Person, die den Link öffnet, nichts._

[Ihre Zusammenfassung]

#### Ziele und Nicht-Ziele

- Ziel: [...]
- Ziel: [...]
- Nicht-Ziel: [...]
- Nicht-Ziel: [...]

#### Der Rest des Designs

_Jeder Teil ist ein eigenes Dokument. Verlinken Sie ihn, statt daraus zu kopieren, damit jede Tatsache an einer Stelle lebt._

- [Kontext und Anforderungen](https://nodary.ai/de/templates/technical-design-document#doc-context): der Ist-Zustand, die Anforderungen und die Rahmenbedingungen
- [Architektur](https://nodary.ai/de/templates/technical-design-document#doc-architecture): die Komponenten, der Weg einer Anfrage und die Schlüsselentscheidungen
- [Daten und Schnittstellen](https://nodary.ai/de/templates/technical-design-document#doc-data): das Datenmodell, die APIs, die Events und die Migration
- [Betrieb](https://nodary.ai/de/templates/technical-design-document#doc-operations): Deployment, Monitoring, Sicherheit und Ausfallarten
- [Alternativen und Risiken](https://nodary.ai/de/templates/technical-design-document#doc-alternatives): verworfene Optionen, Risiken, Rollout und offene Fragen

_Diese Vorlage dürfen Sie frei nutzen, ändern und teilen. Sie stammt von_ [Nodary](https://nodary.ai/de)_, wo sich diese Dateien als Karte verlinkter Dokumente importieren lassen._

### Kontext und Anforderungen

**Verantwortlich:** [Name] · **Status:** Entwurf · **Zuletzt geprüft:** [Datum]

#### Ist-Zustand

_Was heute existiert und was daran nicht stimmt, in wenigen Sätzen. Verlinken Sie den Code, die Dashboards und frühere Designs._

[Ist-Zustand]

#### Anforderungen

_Die Anforderungen, die das Design prägen, jede mit ihrer Quelle verlinkt. Lassen Sie die weg, die das Design nicht berührt._

| ID | Anforderung | Quelle |
| --- | --- | --- |
| [A1] | [...] | [PRD, Vorfall, Vorschrift] |
| [A2] | [...] | [...] |

_Beispiel (ein Beispiel-Feature): A1: Ein Link öffnet sich spätestens eine Minute nach seinem Enddatum nicht mehr. Quelle: die Abnahmekriterien im PRD._

#### Rahmenbedingungen

- Performance: [...]
- Sicherheit und Datenschutz: [...]
- Kompatibilität: [...]
- Team und Zeit: [...]

#### Annahmen

- [Annahme], geprüft von [Name]
- [...]

Siehe auch: [Technisches Designdokument](https://nodary.ai/de/templates/technical-design-document#doc-overview) · [Architektur](https://nodary.ai/de/templates/technical-design-document#doc-architecture)

### Architektur

**Verantwortlich:** [Name] · **Status:** Entwurf · **Zuletzt geprüft:** [Datum]

#### Komponenten

_Ersetzen Sie diese Boxen durch Ihre. Markieren Sie, was neu ist, was sich ändert und was bleibt, wie es ist._

```mermaid
flowchart TD
  n0["Client"]
  n1["API"]
  n2["Dienst"]
  n3["Datenbank"]
  n4["Job-Queue"]
  n5["Dateispeicher"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n2 --> n4
  n4 --> n3
  n2 --> n5
```
_Die Hauptkomponenten und die Aufrufe zwischen ihnen_

| Komponente | Aufgabe | Team | Neu oder geändert |
| --- | --- | --- | --- |
| [API] | [...] | [Team] | [neu, geändert, unverändert] |
| [...] | [...] | [...] | [...] |

#### Weg einer Anfrage

_Folgen Sie einer Anfrage von der Aktion des Nutzers bis zur Antwort. Nummerieren Sie die Schritte: Reviewer kommentieren sie nach Nummer._

1. [Der Nutzer tut ...]
2. [Die API prüft ...]
3. [Der Dienst schreibt ...]
4. [Die Antwort sagt ...]

#### Schlüsselentscheidungen

_Die Entscheidungen, denen ein Reviewer zustimmen muss. Geben Sie jeder wichtigen einen Eintrag im Entscheidungsprotokoll des Teams und verlinken Sie ihn hier._

| Entscheidung | Warum | Eintrag |
| --- | --- | --- |
| [...] | [...] | [Link] |

Siehe auch: [Kontext und Anforderungen](https://nodary.ai/de/templates/technical-design-document#doc-context) · [Daten und Schnittstellen](https://nodary.ai/de/templates/technical-design-document#doc-data) · [Betrieb](https://nodary.ai/de/templates/technical-design-document#doc-operations)

### Daten und Schnittstellen

**Verantwortlich:** [Name] · **Status:** Entwurf · **Zuletzt geprüft:** [Datum]

#### Datenmodell

| Entität | Feld | Typ | Notizen |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [optional, indiziert, personenbezogen] |
| [...] | [...] | [...] | [...] |

_Beispiel (ein Beispiel-Feature): share__link.expires__at: ein Zeitstempel mit Zeitzone, leer, wenn der Link kein Ende hat, indiziert für den Job, der abgelaufene Links widerruft._

#### APIs

| Methode | Pfad | Zweck | Wer sie aufrufen darf |
| --- | --- | --- | --- |
| [POST] | [/...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

#### Events

| Event | Ausgelöst, wenn | Gelesen von |
| --- | --- | --- |
| [...] | [...] | [...] |

#### Migration

_Wie vorhandene Daten ohne Ausfallzeit in die neue Form kommen, und wie Sie das rückgängig machen würden._

1. [Neue Felder anlegen, leer]
2. [In Alt und Neu schreiben]
3. [Bestand nachfüllen]
4. [Aus Neu lesen]
5. [Alt entfernen]

Siehe auch: [Architektur](https://nodary.ai/de/templates/technical-design-document#doc-architecture) · [Betrieb](https://nodary.ai/de/templates/technical-design-document#doc-operations)

### Betrieb

**Verantwortlich:** [Name] · **Status:** Entwurf · **Zuletzt geprüft:** [Datum]

#### Deployment

- Wo es läuft: [...]
- Wie es ausgeliefert wird: [Pipeline, Flags]
- Konfiguration und Secrets: [...]

#### Monitoring und Alarme

| Signal | Normal | Alarm, wenn | Alarm geht an |
| --- | --- | --- | --- |
| [Fehlerrate] | [...] | [...] | [Team] |
| [...] | [...] | [...] | [...] |

#### Sicherheit und Datenschutz

- [ ] Jede Anfrage prüft, wer fragt und was er darf
- [ ] Personenbezogene Daten aufgelistet, mit Speicherort und Aufbewahrungsdauer
- [ ] Secrets weder im Code noch in den Logs
- [ ] Eingaben dort geprüft, wo sie ins System kommen
- [ ] Missbrauch und Ratenbegrenzung bedacht

#### Ausfallarten

| Ausfall | Was Nutzer sehen | Wie wir es merken | Wie wir uns erholen |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

_Beispiel (ein Beispiel-Feature): Der Widerrufs-Job hält an: Abgelaufene Links werden weiter abgewiesen, weil jede Anfrage das Datum prüft; nur das Aufräumen hinkt hinterher. Ein Alarm geht los, wenn der Job fünf Minuten lang nicht gelaufen ist._

Siehe auch: [Architektur](https://nodary.ai/de/templates/technical-design-document#doc-architecture) · [Alternativen und Risiken](https://nodary.ai/de/templates/technical-design-document#doc-alternatives)

### Alternativen und Risiken

**Verantwortlich:** [Name] · **Status:** Entwurf · **Zuletzt geprüft:** [Datum]

#### Erwogene Alternativen

| Option | Dafür | Dagegen | Warum nicht |
| --- | --- | --- | --- |
| [...] | [...] | [...] | [...] |
| [...] | [...] | [...] | [...] |

#### Risiken

| Risiko | Auswirkung | Was wir tun | Verantwortlich |
| --- | --- | --- | --- |
| [...] | [gering, mittel, hoch] | [...] | [Name] |

#### Rollout

1. Hinter einem Flag, für [das Team]
2. [Ein kleiner Teil] der [Nutzer]
3. Alle
4. Flag entfernt

#### Offene Fragen

- [ ] [Frage], [wer sie beantwortet], [bis wann]

Siehe auch: [Technisches Designdokument](https://nodary.ai/de/templates/technical-design-document#doc-overview) · [Kontext und Anforderungen](https://nodary.ai/de/templates/technical-design-document#doc-context) · [Betrieb](https://nodary.ai/de/templates/technical-design-document#doc-operations)

## So nutzen Sie sie

### Von den Anforderungen ausgehen

Verlinken Sie die Produktanforderungen auf der Kontextseite und listen Sie die auf, die das Design prägen. Ein Design, das keine Anforderung erfüllt, ist ein verkapptes Refactoring.

### Erst zeichnen, dann schreiben

Zeichnen Sie die Komponenten und die Aufrufe zwischen ihnen vor dem Fließtext. Reviewer sehen eine fehlende Box schneller als einen fehlenden Absatz.

### Aufschreiben, was Sie verworfen haben

Tragen Sie bei den Alternativen die ernsthaft erwogenen Optionen ein. So öffnet das Review sie nicht einzeln wieder.

### Nach der Umsetzung aktualisieren

Wenn der Code ausgeliefert ist, markieren Sie, was vom Plan abweicht. Wer danach kommt, liest das Design, um zu verstehen, wie das System funktioniert, nicht wie es gedacht war.

## Als Karte in Nodary importieren

Nodary ist ein KI-nativer Workspace, in dem die Dokumente eines Teams verlinkt sind, statt sich zu stapeln. Importieren Sie die .zip, und das Design kommt mit seinen fünf Teilen darunter an, die Links bleiben erhalten und das Diagramm wird als bearbeitbares Mermaid-Diagramm gezeichnet. Reviewer kommentieren eine Passage oder ein Element eines Diagramms, die Autorin bittet um Freigabe, und Coding-Agenten wie Cursor, Claude Code oder VS Code lesen das Design per MCP, bevor sie den Code schreiben.

1. Öffnen Sie die Karte eines Projekts und wählen Sie „Importieren“.
2. Wählen Sie den Tab „Ordner oder ZIP“ und dann „ZIP wählen“.
3. Wählen Sie die heruntergeladene Datei, prüfen Sie die Baumstruktur und importieren Sie.

Der Free-Plan bietet zehn Dokumente pro Workspace, die eigene Seite des Projekts eingerechnet: Die sechs der Vorlage lassen Platz für drei weitere. Nodary hat außerdem eine einseitige Vorlage für ein technisches Design eingebaut.

## Ein Design schreiben, das Reviewer freigeben können

Ein technisches Designdokument scheitert, wenn Reviewer nicht wissen, was sie freigeben, oder wenn das beschriebene System nicht das ist, das ausgeliefert wurde. Diese Gewohnheiten verhindern beides.

### Mit der Entscheidung beginnen

Sagen Sie in der Zusammenfassung, was Sie bauen und welche Wahl ein Reviewer zuerst ansehen sollte. Niemand sollte sie erst auf Seite drei finden.

### Zeichnen vor schreiben

Ein Diagramm aus sechs Boxen und ihren Aufrufen ersetzt sechs Seiten Text und zeigt sofort das fehlende Teil.

### Sagen, was Sie nicht tun

Nicht-Ziele halten das Review beim vorliegenden Design statt bei dem, das jemand lieber gelesen hätte.

### Die verworfenen Optionen zeigen

Sagen Sie für jede wichtige Wahl, was Sie sonst erwogen haben und warum nicht. Reviewer diskutieren dann Ihre Gründe, nicht Ihr Ergebnis.

### Für den Ausfall planen

Sagen Sie, was passiert, wenn jeder Teil ausfällt, wie Sie es bemerken und wie Sie sich erholen. Betrieb ist Teil des Designs, kein Anhang.

### Nach der Umsetzung wahr halten

Markieren Sie, was sich während der Umsetzung geändert hat, und verlinken Sie die Entscheidungen dahinter. Ein Design, das zum Code passt, ist Dokumentation; eines, das nicht passt, ist eine Falle.

## Fragen zum technischen Designdokument

### Was ist ein technisches Designdokument?

Ein technisches Designdokument (Technical Design Document, TDD) beschreibt, wie ein System oder ein Feature gebaut wird, bevor der Code entsteht: Kontext und Anforderungen, Architektur, Daten und Schnittstellen, Deployment und Monitoring, Risiken und erwogene Alternativen. Entwickler schreiben es, damit andere den Ansatz prüfen, solange er sich noch günstig ändern lässt.

### Was gehört in ein technisches Designdokument?

Eine Zusammenfassung mit Zielen und Nicht-Zielen, der Ist-Zustand und die Anforderungen, die Komponenten und wie sie miteinander sprechen, das Datenmodell und die APIs, Deployment, Monitoring, Sicherheit und Ausfallarten, die erwogenen Alternativen, die Risiken, der Rollout-Plan und offene Fragen. Diese Vorlage hat für jede Gruppe ein Dokument.

### Was ist der Unterschied zu einem PRD?

Das Produktanforderungsdokument sagt, was das Feature leisten muss und warum. Das technische Designdokument sagt, wie das System es leistet. Schreiben Sie zuerst das PRD und verlinken Sie es dann im Design, damit sich jede Anforderung nachverfolgen lässt.

### Wann braucht eine Änderung ein Designdokument?

Wenn sie mehrere Komponenten oder Teams betrifft, vorhandene Daten verändert, schwer rückgängig zu machen ist oder ein Risiko trägt, das ein zweites Paar Augen verdient. Eine kleine Änderung innerhalb einer Komponente braucht meist einen guten Pull Request, kein Designdokument.

### Wer sollte ein technisches Designdokument prüfen?

Die Entwickler, die es bauen und betreiben, je ein Entwickler aus jedem betroffenen System und eine für Sicherheit zuständige Person, wenn es um personenbezogene Daten oder Zugriffe geht. Bitten Sie früh um das Review, bevor der meiste Code existiert.

### Schreiben Spieleteams auch technische Designdokumente?

Ja. Die Vorlage für das Game-Design-Dokument hat einen Teil zum technischen Design für Engine, Zielplattformen und Pipeline; ein großes System wie Netzwerk, Speicherstände oder Tools verdient ein eigenes technisches Designdokument, verlinkt aus dem GDD.

Die Seite: https://nodary.ai/de/templates/technical-design-document