Architecture Decision Records für Plattform-Teams

Lernziele

Nach dieser Lektion kannst du ein Architecture Decision Record (ADR) im Nygard-Format schreiben, begründen, welche Entscheidungen ADR-würdig sind, und den Status-Lebenszyklus (Proposed → Accepted → Superseded) erklären. Du weißt, wie ADRs in den Team-Prozess eines Plattform-Teams eingebettet werden — und kannst im Interview ein eigenes ADR als Beleg für Architektur-Reife vorzeigen.

Das Problem: Entscheidungs-Amnesie

Zwei Jahre nach der Einführung fragt eine neue Kollegin: „Warum haben wir eigentlich zwei Policy-Engines im Cluster?” Niemand weiß es mehr genau. Der Architekt von damals ist weg, die Slack-Threads sind unauffindbar, das Confluence-Dokument ist auf Stand eines Zwischenentwurfs. Was bleibt, sind drei gleich teure Reaktionen: Die Entscheidung wird blind respektiert („wird schon Gründe gehabt haben” — auch wenn die Gründe längst weggefallen sind), sie wird blind revidiert (und das Team tritt in genau die Falle, wegen der man sich damals anders entschied), oder sie wird neu ausdiskutiert — dieselbe Debatte, dieselben Argumente, nur ohne das Wissen von damals.

Architekturentscheidungen verlieren ohne Dokumentation nicht ihre Wirkung, sondern nur ihre Begründung. ADRs lösen genau das: kurze, nummerierte Dokumente, die festhalten, was entschieden wurde, in welchem Kontext und mit welchen Konsequenzen — eingeführt von Michael Nygard mit einem bewusst minimalen Format, damit das Schreiben keine Hürde ist.

Das Format: vier Abschnitte, eine Seite

Ein ADR nach Nygard hat Titel, Status und vier Abschnitte. Ein vollständiges Beispiel aus dem Plattform-Alltag:

# ADR-0007: Namespace-basierte Mandantentrennung im Shared Cluster

Status: Accepted (2026-05-12)

## Kontext
Wir betreiben 80 Stream-Teams auf der Plattform. Aktuell laufen keine
regulierten Workloads (kein PCI, kein Patientendatenbezug). Das
Plattform-Team hat 7 Personen; dedizierte Cluster pro Team würden den
Betriebsaufwand vervielfachen. Die Cloud-Kosten stehen unter
Beobachtung des Managements (Ziel: -15 % bis Q4).

## Entscheidung
Teams teilen sich Workload-Cluster pro Umgebung. Isolation erfolgt
über Namespaces mit ResourceQuotas, NetworkPolicies (default-deny)
und Pod Security Standards (restricted). Ein Team = ein Namespace
pro Umgebung.

## Konsequenzen
Positiv: deutlich geringere Cluster-Anzahl und Betriebslast; bessere
Auslastung; Kostenziel erreichbar.
Negativ: schwächere Isolation als dedizierte Cluster — ein
Container-Ausbruch beträfe potenziell Nachbar-Teams; laute Nachbarn
trotz Quotas möglich (z. B. API-Server-Last).
Folgeentscheidungen: Sollten regulierte Workloads kommen, brauchen
diese dedizierte Cluster (neues ADR erforderlich).

## Betrachtete Alternativen
Cluster pro Team: beste Isolation, bei 80 Teams operativ und
finanziell nicht darstellbar. Virtuelle Cluster: interessant, aber
zum Entscheidungszeitpunkt zu wenig Betriebserfahrung im Team.

Drei Eigenschaften machen das Format wirksam: Der Kontext ist der wertvollste Teil — er konserviert die Umstände (Teamgröße, Kostendruck, keine Regulierung), an denen man später prüfen kann, ob die Entscheidung noch trägt. Die Konsequenzen führen ehrlich auch die Nachteile auf — ein ADR, das nur Vorteile listet, ist Marketing, keine Entscheidung. Und das Dokument ist unveränderlich: Stellt sich die Welt anders dar, wird das ADR nicht editiert, sondern von einem neuen abgelöst.

Was ADR-würdig ist — und der Status-Lebenszyklus

Nicht jede Entscheidung verdient ein ADR; wer alles dokumentiert, dokumentiert effektiv nichts, weil das Wichtige im Rauschen verschwindet. Der Filter besteht aus zwei Achsen, die du aus Lektion 6 kennst: Reversibilität (wie teuer ist die Rücknahme?) und Reichweite (wie viele Teams betrifft es, wie lange?). ADR-würdig im Plattform-Kontext sind typischerweise: das Tenancy-Modell, die GitOps- und Policy-Tool-Wahl, die Secrets-Architektur, die Multi-Region-Strategie, jede Build/Buy/Adopt-Entscheidung aus Lektion 11 — und jede Abweichung von einem bestehenden Standard. Nicht ADR-würdig: Variablennamen, einzelne Library-Versionen, alles, was ein Team in einer Stunde zurückdrehen kann.

Der Status macht aus der Sammlung eine nachvollziehbare Geschichte:

• Proposed — zur Diskussion gestellt, noch nicht bindend.
• Accepted — beschlossen; ab jetzt unveränderlich.
• Superseded by ADR-NNNN — abgelöst; das alte ADR bleibt stehen und verweist auf den Nachfolger.
• Deprecated/Rejected — nicht mehr relevant bzw. nach Diskussion verworfen (auch verworfene Vorschläge sind dokumentationswürdig: Sie ersparen die Wiederholung der Debatte).

Die Kette „ADR-0007 superseded by ADR-0023” ist gelebte Architektur-Geschichte: Man sieht nicht nur den heutigen Zustand, sondern den Weg dorthin — inklusive der Umstände, die sich geändert haben.

ADRs im Team-Prozess: leichtgewichtig oder gar nicht

ADRs scheitern fast nie am Format, sondern am Prozess drumherum. Was sich bewährt hat:

Im Repository, nicht im Wiki. ADRs liegen als Markdown im Git-Repo (üblich: docs/adr/ oder docs/decisions/), nummeriert und unveränderlich. Damit durchlaufen sie denselben Review-Mechanismus wie Code: Ein neues ADR ist ein Pull Request, die Diskussion findet im Review statt, der Merge ist die Annahme. Für Plattform-Teams, deren Entscheidungen viele andere Teams betreffen, ist dieser PR genau der richtige Ort, um betroffene Teams einzubinden, bevor entschieden ist.

Klein halten. Eine Seite ist das Ziel, zwei das Maximum. Ein ADR ist kein Architektur-Whitepaper — es beantwortet „was, warum, was folgt daraus”, nicht „wie implementieren wir es im Detail”.

Eine Person entscheidet den Zeitpunkt. Bewährt ist die Regel: Wer eine Entscheidung herbeiführt, schreibt das ADR vor der Umsetzung — als Proposed-PR. Das erzwingt, dass Alternativen und Konsequenzen durchdacht sind, bevor Fakten geschaffen werden, und macht den Entscheidungsprozess selbst transparent.

Auffindbar machen. Ein Index (oder die Einbindung ins Developer Portal aus Lektion 8) sorgt dafür, dass ADRs beim Onboarding und in Diskussionen tatsächlich gefunden werden — das unauffindbare ADR hat denselben Wert wie das ungeschriebene.

Praxis: ein vollständiges ADR schreiben

Schreibe ein echtes ADR — von Hand, im Nygard-Format, maximal eine Seite:

Szenario: Dein Plattform-Team (5 Personen, gute Kubernetes-Kenntnisse, keine Rego-Erfahrung) muss eine Policy-Engine für die Admission Control einführen. Anforderungen: Pflicht-Labels erzwingen, Images nur aus der Haus-Registry, keine privilegierten Container; die Regeln sollen von allen im Team wartbar sein. Kandidaten: Kyverno (Policies als YAML/Kubernetes-Ressourcen) und OPA Gatekeeper (Policies in der Sprache Rego, sehr ausdrucksstark).

1. Schreibe Kontext (Teamgröße, Skills, Anforderungen — alles aus dem Szenario, plus eine plausible eigene Annahme).
2. Triff die Entscheidung in zwei, drei Sätzen.
3. Liste Konsequenzen — mindestens zwei positive, mindestens zwei negative. Die negativen sind der Qualitätstest: Wenn dir keine einfallen, hast du die Alternativen nicht ernst genommen.
4. Dokumentiere die verworfene Alternative mit dem ehrlichen Grund — und einem Satz, unter welchen Umständen sie die bessere Wahl wäre.
5. Härtetest: Gib das ADR jemandem (oder lies es nach zwei Tagen selbst) mit der Frage: „Könntest du allein hiermit die Entscheidung einem Dritten erklären?” Wenn nein: Kontext nachschärfen.

Bewahre das Ergebnis auf — „Ich habe für solche Entscheidungen ADRs geschrieben, zum Beispiel…” ist eine der stärksten Antworten im Interview, und du hast dann eine zur Hand.

Typische Stolperfallen

ADRs nachträglich als Rechtfertigung. Ein ADR, das nach der Umsetzung geschrieben wird, dokumentiert keine Entscheidung, sondern verteidigt sie — Alternativen werden dann rückwirkend schwachgeschrieben. Proposed-Status vor der Umsetzung ist der Schutz dagegen.

Konsequenzen ohne Schattenseite. „Konsequenz: Wir sind jetzt schneller und sicherer” ist ein Werbetext. Jede echte Entscheidung kostet etwas; steht der Preis nicht im ADR, fehlt der wichtigste Teil.

Editieren statt ablösen. Wer ein akzeptiertes ADR „aktualisiert”, zerstört die Geschichtsschreibung — der Kontext von damals geht verloren. Neues ADR, altes auf Superseded.

Der tote Friedhof. Zwanzig ADRs aus dem Gründungsjahr, danach Stille — meist ein Zeichen, dass der Prozess an einer Person hing. Gegenmittel: ADR-Pflicht an die Entscheidungsklasse koppeln (Reversibilität × Reichweite), nicht an Enthusiasmus.

Interview-Vorbereitung

Auf „Wie dokumentierst du Architekturentscheidungen?” antwortest du am stärksten so: Problem (Entscheidungs-Amnesie: Begründungen gehen verloren, Debatten wiederholen sich) → Format (Nygard: Kontext, Entscheidung, Konsequenzen — eine Seite, unveränderlich) → Filter (ADR-würdig = schwer reversibel × große Reichweite) → Prozess (als PR im Repo, Proposed vor der Umsetzung, Superseded statt editieren).

Rechne mit diesen Follow-ups:

• „Was unterscheidet ein gutes von einem schlechten ADR?” — Ehrliche negative Konsequenzen, konservierter Kontext und ernst genommene Alternativen; schlecht: nachträgliche Rechtfertigung ohne Preisschild.
• „Wann lohnt ein ADR nicht?” — Leicht umkehrbare Entscheidungen mit kleiner Reichweite; dort erzeugt Dokumentationspflicht nur Rauschen und Prozessmüdigkeit.
• „Wie geht ihr mit überholten ADRs um?” — Nie editieren: neues ADR schreiben, altes auf „Superseded by” setzen — die Kette ist die Architektur-Geschichte.
• „Wer schreibt das ADR — Architekt oder Team?” — Wer die Entscheidung treibt, schreibt; entschieden wird im Review mit den Betroffenen. ADRs sind ein Kommunikations-, kein Hierarchie-Instrument.

Zusammenfassung

ADRs konservieren das Warum hinter Architekturentscheidungen: Kontext, Entscheidung, Konsequenzen auf einer Seite, unveränderlich, nummeriert, mit Status-Lebenszyklus von Proposed über Accepted bis Superseded. ADR-würdig ist, was schwer reversibel ist und viele betrifft — genau die Entscheidungsklasse aus den Lektionen 6 und 11. Wirksam werden sie durch den Prozess: als Pull Request vor der Umsetzung, mit ehrlichen Nachteilen und ernst genommenen Alternativen.

Damit ist der System-Design-Block abgeschlossen. Die nächste Lektion startet ins IDP-Modul und zerlegt die Schicht, die Entwickler täglich sehen: Portal, Service Catalog und Scaffolding.