Template für Softwarearchitektur-Dokumentation (kostenlos)

So entsteht ein Architekturdokument normalerweise: Eine neue Engineerin fängt an, fragt, wie das System zusammenhängt, und jemand verspricht, „das mal ordentlich aufzuschreiben". Er sucht nach einem Template für Softwarearchitektur-Dokumentation, findet eine vierzigseitige Word-Datei von 2012 oder ein Uni-PDF, füllt die Hälfte aus und öffnet es nie wieder. Ein Jahr später findet die nächste neue Person das Dokument, vertraut ihm und liegt falsch.

Das Problem ist selten ein fehlendes Template. Es sind Templates, die alles verlangen, sodass nichts fertig wird, und Dokumente ohne Owner, sodass nichts aktualisiert wird. Das Template unten ist bewusst schlank: eine Markdown-Datei, neun Abschnitte, jeder davon da, weil jemand, der ihn liest, ihn brauchen wird. Kopieren Sie es in Ihr Repository, ohne Registrierung, ohne Download. Lesen Sie danach die Hinweise Abschnitt für Abschnitt dazu, was in jeden Teil gehört und wie Sie verhindern, dass er veraltet.

Wofür ein Architekturdokument da ist (und wer es liest)

Ein Architekturdokument beantwortet die Fragen, die Code nicht schnell beantworten kann: wofür das System da ist, mit wem es spricht, wie es aufgeteilt ist, warum es so aufgeteilt ist und was bekanntermaßen fragil ist. Es ist keine Design-Spezifikation für ein einzelnes Feature und keine API-Referenz.

Es hat fünf Arten von Lesern, und es hilft, für sie namentlich zu schreiben:

Dient ein Abschnitt in Ihrem Dokument keinem von ihnen, löschen Sie ihn. Diese Regel bringt mehr für die Qualität der Dokumentation als jedes Template.

Eine Anmerkung zu den Begriffen: „Architekturdokument", „System Design Document" (SDD) und „Software Architecture Document" (SAD) werden für ungefähr dasselbe verwendet. SDD-Templates werden meist pro Projekt oder Feature geschrieben und enthalten Detaildesign; ein Architekturdokument beschreibt das System, wie es ist, und ändert sich mit ihm. Das Template hier gehört zur zweiten Art.

Das Template (ein Markdown-Block)

Kopieren Sie es nach docs/architecture.md (oder ARCHITECTURE.md im Root) und füllen Sie es aus. Alles in spitzen Klammern ist ein Platzhalter. Löschen Sie jeden Abschnitt, der nicht zutrifft, statt ihn leer zu lassen.

# <Systemname>: Architektur

| | |
|---|---|
| Owner | <Team oder Person, die dafür verantwortlich ist, dass dies stimmt> |
| Zuletzt geprüft | <JJJJ-MM-TT> |
| Nächste Prüfung | <JJJJ-MM-TT, oder "bei jeder Änderung an den Abschnitten 3-5"> |
| Status | <Entwurf / aktuell / wird ersetzt durch X> |

## 1. Kontext und Umfang

<Zwei oder drei Sätze: was das System tut, für wen und warum es existiert.>

**Nutzer**
- <Rolle>: <was sie mit dem System tun>

**Externe Systeme**
- <System>: <was wir senden oder empfangen, Protokoll>

**Nicht im Umfang**
- <Dinge, von denen man annimmt, dass dieses System sie tut, was es aber nicht tut>

**System-Context-Diagramm (C4-Ebene 1)**
<Link oder Einbettung. Das System als ein Kasten, jede Art von Nutzer, jedes externe System.>

## 2. Qualitätsziele

Die drei bis fünf Qualitäten, die sich durchsetzen, wenn sie miteinander in Konflikt geraten, in Prioritätsreihenfolge.

| Priorität | Qualität | Konkretes Szenario |
|---|---|---|
| 1 | <z. B. Verfügbarkeit> | <z. B. Der Checkout funktioniert weiter, wenn der Empfehlungsservice ausgefallen ist> |
| 2 | <z. B. Latenz> | <z. B. p95 des Checkouts unter 2 s bei 500 Bestellungen/Minute> |
| 3 | <z. B. Änderbarkeit> | <z. B. Eine neue Zahlungsmethode geht live, ohne den Order Service anzufassen> |

## 3. Randbedingungen

Dinge, die wir nicht gewählt haben, mit denen wir aber leben müssen.
- <z. B. Läuft auf der Kubernetes-Plattform des Unternehmens>
- <z. B. Kundendaten bleiben in der EU>
- <z. B. Backend-Services nur in Go oder Java>

## 4. Architektur

**Container-Diagramm (C4-Ebene 2)**
<Link oder Einbettung. Jede deploybare Einheit und jeder Datenspeicher, mit Technologie und Protokollen.>

| Container | Technologie | Verantwortung | Owner |
|---|---|---|---|
| <Web-App> | <React SPA> | <Was er tut> | <Team> |
| <API> | <Go> | <Was er tut> | <Team> |
| <Datenbank> | <PostgreSQL> | <Was sie speichert> | <Team> |

**Komponentendiagramme (C4-Ebene 3)**
<Nur für den einen oder die zwei Container, mit denen sich Neue schwertun würden. Link oder Einbettung.>

**Zentrale Abläufe**
<Die zwei oder drei wichtigsten Szenarien, als nummerierte Schritte oder als dynamisches C4-Diagramm.>

1. <Akteur> -> <Container>: <was passiert>
2. <Container> -> <Container>: <was passiert, Protokoll, synchron oder asynchron>

## 5. Zentrale Entscheidungen

Die vollständigen Records liegen in <docs/adr/>. Dies ist der Index.

| ADR | Entscheidung | Status | Datum |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <z. B. Eine Datenbank pro Service> | Akzeptiert | <JJJJ-MM-TT> |
| [ADR-002](adr/002-<slug>.md) | <z. B. Kafka für Bestell-Events> | Akzeptiert | <JJJJ-MM-TT> |

## 6. Querschnittliche Themen

Wie das Gesamtsystem Dinge handhabt, die jeder Container berührt. Je eine oder zwei Zeilen, mit Link zu Details.
- **Authentifizierung und Autorisierung:** <wo sie stattfindet, welches Token>
- **Observability:** <Logs, Metriken, Traces, wo man nachsieht>
- **Fehlerbehandlung und Retries:** <Konventionen, Idempotenz>
- **Daten und Datenschutz:** <wo personenbezogene Daten liegen, Aufbewahrung>

## 7. Deployment und Betrieb

- **Umgebungen:** <Produktion, Staging, ...> und wie sie sich unterscheiden
- **Wo es läuft:** <Cloud, Region, Cluster>
- **Runbooks:** <Link>
- **Dashboards und Alerts:** <Link>

## 8. Risiken und technische Schulden

| Risiko oder Schuld | Auswirkung, wenn es eintritt | Plan | Owner |
|---|---|---|---|
| <z. B. Bestand wird vor der Zahlung reserviert, keine Kompensation> | <Verwaiste Reservierungen nach fehlgeschlagenen Zahlungen> | <Freigabe bei Fehler ergänzen, Q4> | <Team> |

## 9. Glossar

| Begriff | Bedeutung hier |
|---|---|
| <Bestellung> | <Definition, wie das Fachgebiet sie verwendet> |

Das ist das ganze Template. Ausgefüllt für ein System mit etwa zehn Containern umfasst es typischerweise ein paar Seiten. Wird Ihres deutlich länger, gehört etwas darin vermutlich in ein verlinktes Dokument statt in dieses.

Abschnitt für Abschnitt

Kopfzeilen: Owner und Prüfdatum

Die vier Zeilen oben sind wichtiger als jeder Abschnitt darunter. Owner sagt, wer das Dokument korrigiert, wenn es falsch ist. Zuletzt geprüft sagt einem Leser, wie sehr er ihm trauen kann. Ein Dokument, das sagt „zuletzt geprüft vor vierzehn Monaten", ist ehrlich; eines, das nichts sagt, wirkt aktuell, obwohl es das nicht ist.

1. Kontext und Umfang

Fangen Sie hier an, weil jeder andere Abschnitt von der Grenze abhängt. Listen Sie jede Art von Nutzer und jedes externe System auf, auch die, die Sie für selbstverständlich halten (Identity Provider, E-Mail-Service, Payment Gateway). Die Liste Nicht im Umfang spart mehr Meetings als alles andere im Dokument: Hier halten Sie fest, dass dieses System keine Erstattungen abwickelt, auch wenn alle annehmen, dass es das tut.

Das Diagramm ist ein C4-System-Context-Diagramm: Ihr System als ein Kasten, Nutzer und externe Systeme darum herum, beschriftete Pfeile. Der Leitfaden zum System-Context-Diagramm erklärt, was hineingehört.

2. Qualitätsziele

Die meisten Architekturdokumente lassen diesen Abschnitt weg, dabei erklärt er den Rest. „Verfügbarkeit vor Konsistenz" oder „Änderbarkeit vor reiner Performance" sagt einem Leser, warum die Container so aussehen, wie sie aussehen. Beschränken Sie sich auf drei bis fünf Ziele, bringen Sie sie in eine Rangfolge und geben Sie jedem ein Szenario, das konkret genug ist, um es zu testen: eine Zahl, eine Last, einen Ausfall.

3. Randbedingungen

Randbedingungen sind die Entscheidungen, die jemand anderes getroffen hat: das Plattformteam, die Rechtsabteilung, die Sprachvorgaben des Unternehmens. Schreibt man sie auf, beendet das die Diskussion „warum habt ihr nicht einfach X genommen?", und ein künftiger Leser weiß, welche Entscheidungen sich neu verhandeln lassen und welche nicht.

4. Architektur: die C4-Diagramme

Das ist der Abschnitt, den die meisten für „die Architektur" halten. Nutzen Sie das C4-Modell, weil es jedem Diagramm genau eine Aufgabe gibt:

• Container-Diagramm (Ebene 2), immer. Jede deploybare Einheit und jeder Datenspeicher, jeweils mit Technologie, jeder Pfeil mit Protokoll. Wenn Sie nur ein Diagramm zeichnen, dann dieses. Der Leitfaden zum Container-Diagramm enthält ein durchgearbeitetes Beispiel.
• Komponentendiagramme (Ebene 3), selektiv. Nur für Container, mit denen sich Neue schwertun würden.
• Zentrale Abläufe. Zwei oder drei Szenarien als nummerierte Schritte. Ein statisches Diagramm zeigt, dass zwei Container miteinander sprechen; ein Ablauf zeigt, in welcher Reihenfolge und auf welche Schritte der Nutzer wartet. Der Leitfaden zum dynamischen C4-Diagramm zeigt, wie man einen schreibt.

Die Container-Tabelle mit der Spalte Owner ist Absicht. Ein Container, der niemandem gehört, ist einer, den auch in diesem Dokument niemand aktualisiert.

Wenn C4 neu für Sie ist, erklärt was das C4-Modell ist die vier Ebenen. Beispiele für diese Diagramme an realen, großen Systemen finden Sie in unseren C4-Modell-Beispielen.

5. Zentrale Entscheidungen (ADRs)

Schreiben Sie Entscheidungen nicht in den Fließtext. Halten Sie jede als Architecture Decision Record in einer eigenen Datei fest (Kontext, Entscheidung, betrachtete Alternativen, Konsequenzen) und behalten Sie hier nur den Index. ADRs werden einmal geschrieben und abgelöst statt bearbeitet, so bleibt das Dokument kurz und die Historie intakt. Der vollständige Leitfaden zu Architecture Decision Records behandelt das Format und wann eine Entscheidung einen ADR verdient.

Ein guter Test für den Index: Eine neue Engineerin sollte auf jeden überraschenden Kasten in Abschnitt 4 zeigen und den ADR finden können, der ihn erklärt.

6. Querschnittliche Themen

Manche Dinge leben in keinem einzelnen Container: Authentifizierung, Logging, Fehlerbehandlung, wo personenbezogene Daten liegen. Je eine oder zwei Zeilen reichen, mit einem Link zu den Details. In diesem Abschnitt verbringt ein Auditor die meiste Zeit, machen Sie es ihm also leicht.

7. Deployment und Betrieb

Halten Sie das kurz und verlinken Sie nach außen. Umgebungen und wie sie sich unterscheiden, wo das System läuft, und Links zu Runbooks und Dashboards. Die Details gehören in Ihren Infrastruktur-Code und Ihre Runbooks, die sich öfter ändern, als es dieses Dokument sollte.

8. Risiken und technische Schulden

Der ehrliche Abschnitt. Schreiben Sie auf, was bekanntermaßen fragil ist, mit Owner und Plan, auch wenn der Plan „akzeptiert, in Q3 neu bewerten" lautet. Ein aufgeschriebenes Risiko ist eines, das jemand priorisieren kann. Ein Risiko, das nur im Kopf eines Engineers existiert, geht mit ihm.

9. Glossar

Jedes System hat Wörter, die hier etwas Bestimmtes bedeuten: „Bestellung" vs. „Warenkorb", „Account" vs. „Tenant", „Fulfilment". Definieren Sie jedes einmal. Neue Engineers lesen diesen Abschnitt öfter, als man erwarten würde.

Wie sich das zu arc42 verhält

Wenn Ihnen dieses Template bekannt vorkommt, liegt das daran, dass es eine schlanke Fassung derselben Ideen wie arc42 ist, dem kostenlosen Open-Source-Template für Architekturdokumentation von Peter Hruschka und Gernot Starke. arc42 hat zwölf Abschnitte und rät selbst, „nur das, was Ihre Stakeholder brauchen" zu dokumentieren (arc42 FAQ, B-1). Die Zuordnung:

Wählen Sie arc42, wenn Sie seine vollständige Struktur brauchen: regulierte Umgebungen, große Systeme mit mehreren Architekten oder eine Organisation, die bereits darauf standardisiert. Wählen Sie etwas in dieser Größe, wenn die Alternative gar kein Dokument ist. Einen ausführlichen Vergleich, einschließlich welches C4-Diagramm in welchen arc42-Abschnitt gehört, finden Sie unter arc42 vs. C4.

Wie es nicht veraltet

Jedes Architekturdokument ist an dem Tag korrekt, an dem es gemergt wird. Ob es in sechs Monaten noch korrekt ist, hängt von ein paar Gewohnheiten ab, die meisten davon betreffen die Diagramme, weil sich in den Abschnitten 4 und 5 die Realität am schnellsten ändert.

Halten Sie es im Repository. docs/architecture.md neben dem Code bedeutet, dass ein Pull Request, der einen Service aufteilt, die Container-Tabelle im selben Review aktualisieren kann. Eine Wiki-Seite kann nicht Teil eines Code-Reviews sein.

Verlinken Sie Diagramme, fügen Sie keine Screenshots ein. Ein Screenshot des Container-Diagramms ist in dem Moment veraltet, in dem ein Container umbenannt wird. Ein Diagramm, das aus einem Modell gerendert wird (Structurizr-DSL, ein YAML-Modell oder ein Tool, das eines hält), ist nur so veraltet wie das Modell.

Nutzen Sie das Prüfdatum aktiv. Nehmen Sie das Dokument in jede Checkliste auf, die läuft, wenn ein Container hinzugefügt oder entfernt wird: das Pull-Request-Template, das Architektur-Review, die Quartalsplanung. „Nächste Prüfung: bei jeder Änderung an den Abschnitten 3 bis 5" ist ein gültiger Eintrag.

Schreiben Sie Entscheidungen fort. Bearbeiten Sie nie einen akzeptierten ADR. Lösen Sie ihn ab. Der Index in Abschnitt 5 zeigt dann die Historie, und die brauchen die Leute am meisten.

Prüfen Sie die strukturellen Teile automatisch. Die Abschnitte 1 und 4 beschreiben Dinge, die im Code existieren: Services, Datenspeicher, Abhängigkeiten. Die lassen sich mit dem Repository abgleichen. Die Abschnitte 2, 6 und 8 nicht; sie brauchen eine Person, nach Plan. Der Leitfaden zur Erkennung von Architektur-Drift behandelt die Methoden für die erste Art und was jede davon sehen kann und was nicht.

Genau für dieses Problem ist archyl gebaut, für die Diagramm-Hälfte des Dokuments. Verbinden Sie ein Repository, und die KI-Erkennung schlägt das C4-Modell vor (Systeme, Container, Komponenten und Beziehungen), das Sie prüfen und freigeben, statt es zu zeichnen. ADRs, Docs und Flows sind mit den Elementen verknüpft, die sie beschreiben. Ein Drift-Score prüft dann, ob die dokumentierten Elemente noch im Code existieren, deterministisch und ohne KI im Prüfpfad, sodass ein veralteter Abschnitt 4 als Zahl sichtbar wird statt als Überraschung. Ihre Qualitätsziele oder Ihre Risikoliste prüft er nicht; die brauchen weiterhin das Prüfdatum. Die Praktiken, die Dokumentation mit oder ohne Tool aktuell halten, finden Sie unter lebende Architekturdokumentation.

FAQ

Was sollte ein Softwarearchitektur-Dokument enthalten?

Mindestens: Kontext und Umfang des Systems (Nutzer und externe Systeme), ein Diagramm auf Container-Ebene mit Technologien, die zentralen Architekturentscheidungen mit ihren Gründen, die bekannten Risiken und einen Owner mit Prüfdatum. Das Template oben ergänzt Qualitätsziele, Randbedingungen, querschnittliche Themen, Deployment-Hinweise und ein Glossar, alles kurz.

Ist dieses Template wirklich kostenlos?

Ja. Es ist der Markdown-Block oben. Kopieren Sie ihn und passen Sie ihn an Ihr System an. Keine Registrierung, kein Download, keine E-Mail.

Wo sollte das Architekturdokument liegen?

Im Repository, als docs/architecture.md oder ARCHITECTURE.md, neben den ADRs in docs/adr/. So laufen Änderungen an der Architektur und Änderungen am Dokument durch denselben Pull Request.

Wie lang sollte ein Architekturdokument sein?

So kurz, wie es sein kann, während es die Fragen seiner Leser beantwortet. Für ein System mit rund zehn Containern sind ein paar Seiten normal. Wächst es deutlich darüber hinaus, verschieben Sie Details in verlinkte Dokumente (Runbooks, ADRs, API-Referenzen) und behalten Sie dieses als Karte.

Was ist der Unterschied zu einem System Design Document?

Ein System Design Document wird meist für ein Projekt oder Feature geschrieben, bevor es gebaut wird, und enthält Detaildesign. Ein Architekturdokument beschreibt das ganze System, wie es jetzt ist, und ändert sich mit ihm. Teams haben oft ein Architekturdokument pro System und viele Design-Dokumente über seine Lebensdauer, wobei die dauerhaften Entscheidungen aus den Design-Dokumenten als ADRs enden.

Sollte ich stattdessen arc42 verwenden?

Wenn Sie seine vollständige Struktur brauchen oder Ihre Organisation es bereits nutzt, ja. Dieses Template lässt sich auf die Abschnitte von arc42 abbilden (siehe Tabelle oben), Sie können also hier anfangen und später in arc42 hineinwachsen, ohne etwas neu zu schreiben.

Sollen die Diagramme in Abschnitt 4 aus Ihrem Code kommen statt aus dem Gedächtnis? Testen Sie archyl kostenlos im Developer-Plan, ohne Kreditkarte. Weiterlesen: arc42 vs. C4 | Architecture Decision Records: Der vollständige Leitfaden | Was ist das C4-Modell? | Lebende Architekturdokumentation | Erkennung von Architektur-Drift.