Zum Inhalt springen
Engineer
Menü
Design
Deutsch

Engineer / Glossar

Architekturentscheidungsprotokoll

kurzer Vermerk zur Architekturentscheidung und ihren Gründen

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

Kontakt

Sie klären noch, was Sie benötigen?

Erzählen Sie uns, was nicht funktioniert oder was Sie entwickeln möchten. Wir sagen Ihnen, was dafür nötig wäre, was es ungefähr kosten würde und ob wir die Richtigen dafür sind.

Ab 1.400 DKK pro Stunde, zuzüglich Mehrwertsteuer — und weniger pro Stunde bei längerer Buchung.

welcome@engineer.company +45 50 10 61 84 Kopenhagen, Dänemark