Architekturentscheidungsprotokoll

Was es ist

Ein Architekturentscheidungsprotokoll, häufig ADR genannt, hält eine
technische Entscheidung mit weitreichenden Folgen fest. Es
beschreibt, was ein Team beschlossen hat, unter welchen Bedingungen,
welche anderen Möglichkeiten zur Wahl standen und welche Folgen es
in Kauf nahm. Es kann etwa darum gehen, wem ein Datenbestand gehört,
wie Dienste gekoppelt sind oder wie eine Anwendung bei einem Ausfall
reagieren soll. Wer später dazukommt, kann nachvollziehen, warum der
Entwurf so aussieht und ob seine Voraussetzungen noch gelten.

Ein paar Angaben geben dem Dokument eine brauchbare Form. Nummer und
Datum machen es zitierbar. Der Status zeigt, ob ein Vorschlag
vorliegt, die Entscheidung gilt oder eine neue sie ablöst. Der
Kontext benennt das Problem und die Einschränkungen. Die
Entscheidung beschreibt die geplante Umsetzung. Die Folgen umfassen
Gewinn und Aufwand. Vielleicht muss ein weiterer Dienst betreut,
eine längere Umstellung eingeplant oder ein Datenumzug geprobt
werden. Schildern Sie die erwogenen Alternativen so, dass sich die
Abwägung erkennen lässt.

Legen Sie das Protokoll dort ab, wo die Beteiligten arbeiten. Ein
Team kann Markdown-Dateien beim Quellcode führen und aus der
umsetzenden Änderung darauf verweisen. Bei mehreren beteiligten
Teams kann ein gemeinsames Verzeichnis sinnvoll sein. Eine stabile
Adresse und eine eigenständig verständliche Begründung erleichtern
die Übergabe. Messwerte, überprüfte Anforderungen und Testergebnisse
können mit dem Protokoll verknüpft werden.

Warum es wichtig ist

Code dokumentiert viel vom heutigen Stand. Die Gründe für frühere
Entscheidungen sind oft nur teilweise zu erkennen. Zwei Datenbanken
können wie zufällig gewachsene Doppelarbeit aussehen. Vielleicht war
die Trennung eine Vorsichtsmaßnahme, während ein Lieferant sein
Exportformat umstellte. Ein Protokoll kann benennen, was das Team
schützen wollte, warum es diese Wahl traf und welches Ereignis eine
Neubewertung auslöst. Die nächste Person muss die Untersuchung dann
nicht von vorn beginnen.

Ein Protokoll erleichtert auch einen konkreten Einwand. Ein
Vorschlag kann zeigen, dass eine neue Abhängigkeit einen selbst
entwickelten Planer erspart. Durch die Abhängigkeit muss im
Bereitschaftsdienst jemand deren Zustand wiederherstellen können.
Eine Kollegin kann fragen, ob der Aufwand dafür bekannt ist und die
nötige Berechtigung vorliegt. Betriebsverantwortliche sehen die
Abwägung, bevor entschieden wird. Bei der Übergabe kann das neue
Team auf derselben Erklärung aufbauen.

Der Umfang sollte zu den Kosten einer späteren Änderung passen. Eine
geänderte Beschriftung lässt sich meist anhand des Änderungsverlaufs
erklären. Wer das Bestellregister besitzt oder wie doppelte
Zahlungen verhindert werden, betrifft mehrere Teams und lässt sich
aufwendiger ändern. Schreiben Sie den wesentlichen Grund auf,
während die Alternativen noch bekannt sind. Die Belege sollten
zeigen, was zum Zeitpunkt der Entscheidung tatsächlich bekannt war.

Wie es in der Praxis aussieht

Die Arbeitsprobe zu den grundlegenden technischen Entscheidungen für
eine Plattform beschreibt, wie zentrale Technologien gewählt wurden,
während sich die Ausrichtung des Produkts entwickelte. So ein
Wahlpunkt verdient eine nachvollziehbare Begründung. Das folgende
fiktive Beispiel zeigt eine Möglichkeit, die Entscheidung über
Datenverantwortung festzuhalten.

Ein Versanddienst hat eine Bestelldatenbank und eine öffentliche
Seite, auf der Kunden den Stand ihrer eigenen Bestellung sehen.
Statusereignisse treffen gelegentlich spät ein. Die Seite darf keine
fremde Bestellung preisgeben. Das Team entscheidet sich für ein
getrenntes Lesemodell, das nur freigegebene Felder erhält. Der
direkte Abruf aus der Bestelldatenbank hätte weniger Komponenten und
meist aktuellere Daten bedeutet. Er hätte auch öffentlichen Verkehr
und eine neue Berechtigungsgrenze an das maßgebliche Register
herangeführt. Der vorhandene nächtliche Export wäre leicht
wiederzuverwenden, würde Änderungen am selben Tag aber nicht zeigen.

Aus den Folgen werden Aufgaben. Die Hilfestelle braucht eine Anzeige
für verspätete Daten, damit sie bei Bedarf ein internes Verfahren
verwenden kann. Ein Schnittstellentest kann ein unbeabsichtigt
hinzugefügtes Feld feststellen. Der Aktualisierungslauf und sein
Alarm bekommen eine verantwortliche Person. Das Team vereinbart eine
Neubewertung bei anhaltender Verzögerung in zwei Wochen mit hoher
Last oder wenn sich das Trennungsgebot ändert. Das Protokoll
verlinkt die Untersuchung und den Test.

Wenn ein späterer Beschluss die ursprüngliche Wahl ablöst, bekommt
er einen eigenen Eintrag. Verweise in beide Richtungen verbinden die
Gründe. Wer einen Fehler in einer alten Version sucht, kann immer
noch nachlesen, warum sie damals anders aufgebaut war.

Vor der Ausgabe prüft der öffentliche Dienst, ob der Besucher genau
diese Bestellung sehen darf. Testen Sie die Ablehnung bei einem
fremden Auftrag und den genauen Feldumfang bei einem zulässigen
Abruf.

Wo es schiefgeht

Ein Protokoll verliert an Wert, wenn nur die Lieblingslösung
sorgfältig dargestellt wird. Nennen Sie die brauchbaren Alternativen
mit ihren stärksten tatsächlichen Gründen. In einer anderen Lage
hätten sich dieselben Gründe anders verteilt. Wichtige Aussagen
sollten auf die Messung, Regel oder Einschränkung verweisen, die
wirklich zur Entscheidung beigetragen hat.

Auch Folgekosten können im Dokument fehlen. Eine zweite Datenbank
oder eine gemeinsame Warteschlange verändert den Arbeitsalltag einer
anderen Person. Nennen Sie Zuständigkeiten für Betrieb,
Zugriffsgrenzen und Wartung. Lässt sich eine Folge noch nicht
prüfen, legen Sie fest, welche Beobachtung sie bestätigen würde und
wann diese möglich wird.

Schreiben Sie schließlich knapp genug, dass der Text während der
Entscheidung entstehen kann. Betriebsanleitungen gehören an einen
Ort, an dem sie sich unabhängig ändern lassen. Bei einem neuen
Beschluss bleiben die alten Gründe erhalten, und Leser können den
geltenden Stand an Datum, Status und Verweis erkennen.

Ein Eintrag kann außerdem kennzeichnen, wer über eine Ausnahme
entscheiden darf. Wenn die Trennung im Versandbeispiel für eine
manuelle Korrektur aufgehoben werden soll, braucht das Team einen
nachvollziehbaren Anlass, eine zeitliche Grenze und eine Rückkehr
zum Normalbetrieb. So bleibt klar, welcher Teil der Wahl weiterhin
gilt.

Weiterführende Lektüre

  * AWS zum Ablauf bei Architekturentscheidungsprotokollen

  * Microsoft Azure Well-Architected zu Entscheidungsprotokollen

  * Rahmen der britischen Regierung für Architekturentscheidungen

hDiese Seite im Web	URL:https://engineer.company/de/glossary/architecture-decision-record/	engineer.company	70
