Entscheidungen, die man in zwei Jahren noch versteht

Jedes System, das älter als ein Jahr ist, hat Stellen, an denen ein neues Teammitglied fragt: „Warum ist das so?“ Und die ehrliche Antwort lautet zu oft: „Das weiss nur noch jemand, der nicht mehr da ist.“

Ein ADR ist eine Seite, nicht ein Dokument

Ein Architecture Decision Record hält fest, was entschieden wurde, warum, und was man dafür in Kauf nimmt. Er hat vier Abschnitte und passt auf einen Bildschirm:

• Kontext – Was war die Situation? Welche Zwänge gab es?
• Entscheidung – Was tun wir?
• Alternativen – Was haben wir verworfen, und warum?
• Konsequenzen – Was wird dadurch einfacher, was schwieriger?

Er liegt im Repository, neben dem Code, den er erklärt. Nicht im Wiki, nicht in einem Ticket, nicht in einer Slack-Nachricht.

Warum das mehr bringt als jede Doku

Dokumentation beschreibt, wie ein System ist. Sie veraltet in dem Moment, in dem sich das System ändert. Ein ADR beschreibt, warum es so wurde. Das veraltet nie – selbst wenn die Entscheidung später revidiert wird, bleibt der Record wahr. Man ergänzt einen neuen, der auf den alten verweist.

Ein System ohne Entscheidungsgeschichte ist wie ein Vertrag ohne Datum. Man kann ihn lesen, aber nicht einordnen.

Wie wir es im Alltag halten

• Jede Entscheidung, die schwer rückgängig zu machen ist, bekommt einen ADR. Datenbankwahl, Modulschnitt, Auth-Modell – ja. Farbe des Buttons – nein.
• Der ADR entsteht vor der Umsetzung und wird im selben Pull Request reviewt.
• Nummeriert, chronologisch, nie gelöscht. Überholt wird ein Record durch einen neuen, nicht durch Editieren.

Der Aufwand: zwanzig Minuten pro Entscheidung. Der Ertrag: ein Team, das auch nach dem dritten Wechsel noch weiss, warum das System aussieht, wie es aussieht.