Software-Architektur ohne Zeremonie: Entscheidungen, die altern dürfen

In jedem zweiten Projekt finde ich denselben Stapel: ein zwölfseitiges Architekturpapier vom Projektstart, zur Hälfte überholt, das niemand mehr liest. Daneben Wiki-Seiten mit Diagrammen, in denen Komponenten auftauchen, die längst gelöscht sind. Und dann die echte Wahrheit: in Slack-Threads, Pull-Request-Kommentaren und im Kopf des einen Entwicklers, der seit fünf Jahren dabei ist.

Es muss nicht so sein. Aber es braucht eine andere Haltung gegenüber Architektur-Dokumentation.

Architektur ist kein Plan – sie ist Entscheidungsgeschichte

Der wichtigste Perspektivwechsel: Architekturdokumentation beschreibt nicht, wie das System aussieht. Sie beschreibt, welche Entscheidungen wir wann und warum getroffen haben. Der heutige Stand des Systems ist im Code – dort ist er auch am korrektesten.

Was im Code nicht steht, ist das Warum. Warum dieser Message-Broker statt einer Datenbank? Warum dieser Authentifizierungsfluss statt OIDC out of the box? Warum drei Services und nicht einer?

Diese Fragen stellt jeder neue Mitarbeiter spätestens in der zweiten Woche. Und ohne dokumentierte Antworten geht das Team in eine kollektive Amnesie über, in der jede Entscheidung alle paar Jahre neu gefällt wird – meist mit einem anderen Ergebnis und immer mit Reibungsverlust.

ADRs: kurz, datiert, ehrlich

Mein Werkzeug der Wahl sind Architecture Decision Records. Eine kurze Markdown-Datei pro Entscheidung, im Repository, mit drei Pflichtteilen:

Kontext: Was war die Situation, als wir entschieden haben?
Entscheidung: Was haben wir konkret gewählt?
Konsequenzen: Was kostet uns diese Wahl, was bekommen wir dafür?

Optional, aber in der Praxis sehr hilfreich:

Alternativen: Was haben wir ausgeschlossen und warum?
Status: vorgeschlagen, akzeptiert, abgelöst – mit Datum.

Das war’s. Eine ADR ist selten länger als eine Bildschirmseite.

Warum das altert

Der eigentliche Wert: Wenn in zwei Jahren jemand fragt, warum dieser Service so aussieht, wie er aussieht, finden sie das ADR. Sie sehen den Stand der Welt von damals – andere Datenmengen, andere Compliance-Anforderungen, andere Teamgröße. Sie können fundiert entscheiden, ob die alte Wahl noch passt oder ob es Zeit für einen Nachfolger-ADR ist.

Im Vergleich dazu altert ein klassisches Architekturdokument auf der ersten Seite: “Im Mai 2024 entschieden wir uns für …” und ab Juni stimmt schon die Hälfte nicht mehr.

Praktischer Einstieg

Wenn Sie damit anfangen wollen: Schreiben Sie diese Woche ein einziges ADR – über die nächste Entscheidung, die in Ihrem Team ansteht. Nicht über alle alten. Vorwärts arbeiten, nicht rückwärts. Nach drei Monaten haben Sie eine kleine Sammlung lebender Geschichte – und ein Dokumentationsformat, das nicht mehr zur Last wird.

Wenn Sie für die Einführung von ADRs oder eine größere Architektur-Inventur einen Sparringspartner brauchen, schreiben Sie mir.