Eine Einführung in ADRs (Architecture Decision Records) — Der minimale Weg, „warum wir es so entworfen haben“ in einem kleinen Team festzuhalten
· Go Komura · Design, Design-Review, Dokumentation, ADR, Technische Beratung, Wartung, Auftragsentwicklung, Windows-Entwicklung
„Warum wird hier eine Dateiübergabe verwendet? Wäre es nicht einfacher, einfach die Datenbank abzufragen?“ — ein Entwickler, der den Code eines geerbten Systems öffnet, stößt fast unweigerlich auf eine solche Frage. Und öfter als nicht ist die Person, die die Antwort kannte, das Projekt bereits verlassen.
Es gab sicher einen Grund. Vielleicht wurde die Erlaubnis, direkt mit der Datenbank des anderen Systems zu verbinden, nie erteilt, oder vielleicht war das die einzige Methode, die sicher genug war, um den damaligen Termin zu halten. Bleibt diese Begründung jedoch nicht erhalten, erstarrt der Nachfolger entweder vor Code, bei dem er nicht weiß, ob es sicher ist, ihn anzufassen, oder er prescht vor und zerstört genau das, was die Begründung eigentlich schützen sollte.
Auf diesem Blog haben wir behandelt, wie man eine Auftragsentwicklung führt, in Worüber Sie sich vor der Auslagerung der Windows-App-Entwicklung Klarheit verschaffen sollten, sowie den Vertragsrahmen in Die Wahl zwischen Geschäftsbesorgung und Werkvertrag — Lehren aus der IPA-„Muster-Transaktion und -Vertrag“. Dieser Artikel knüpft daran an und behandelt, was nötig ist, um ein System noch Jahre nach seiner Erstellung am Laufen zu halten. Wir erklären ADRs (Architecture Decision Records) — einen Mechanismus, um die Begründung hinter einer Designentscheidung mit minimalem Aufwand zu bewahren —, ausgehend von einem kleinen Rahmen für Auftrags- oder interne Entwicklung.
1. Das Ergebnis zuerst
- Vor einem umfassenden Design-Dokument sollten Sie ein Protokoll von Entscheidungen bewahren. Was in der Wartung wirklich Ärger verursacht, ist nicht, nicht zu wissen, was der Code tut — sondern nicht zu wissen, warum es so gemacht wurde.
- Ein ADR ist ein leichtgewichtiges Format, das eine einzelne Entscheidung in einer Datei festhält, in der festen Form Titel / Status / Kontext / Entscheidung / Konsequenzen. Michael Nygard schlug es 2011 vor, und die Faustregel ist höchstens ein bis zwei Seiten pro Entscheidung.1
- Es lebt im selben Repository wie der Code (z. B.
docs/adr/0001-titel.md) — unter Versionskontrolle zusammen mit dem Code, gemeinsam mit dem Code-Review geprüft, statt in einem Wiki oder einem gemeinsamen Ordner.12 - Eine Entscheidung wird nie überschrieben. Ändern Sie die Richtung, fügen Sie ein neues ADR hinzu und setzen Sie den Status des alten ADR auf Superseded, mit einer Querverweisung zwischen beiden. Ein ADR-Log ist Append-Only.2
- Statt alles aufzuschreiben, schreiben Sie nur Entscheidungen auf, die sich später schwer ändern lassen, mehrere gleichermaßen vertretbare Alternativen hatten oder durch eine Einschränkung entschieden wurden. Namensregeln und Formatierungseinstellungen sind außerhalb des Umfangs.2
- Aus eigener Erfahrung: Jedes auf 15 bis 30 Minuten Schreibzeit zu begrenzen ist es, was die Gewohnheit hält. Eine schwergewichtige Vorlage stirbt nach den ersten drei Einträgen aus.
- In der Auftragsentwicklung wird ein ADR zu einem Liefergegenstand, den Sie mit dem Auftraggeber teilen können. Es funktioniert unverändert als Erklärungsdokument bei der Abnahme und als Übergabedokument bei einem Personal- oder Anbieterwechsel.
2. Das Problem „Warum ist das so?“
2.1 Code sagt Ihnen das Was, nie das Warum
Lesen Sie den Code, und mit genug Zeit finden Sie heraus, was er tut. Was Sie nicht herausfinden können, ist das Warum hinter Dingen wie diesen.
- Warum ist die Datenbank SQLite statt SQL Server?
- Warum tauscht die Integration mit dem anderen System CSV-Dateien aus, statt eine Web-API zu nutzen?
- Warum startet nur dieser eine Bericht Excel zum Drucken?
- Warum läuft es immer noch auf .NET Framework statt auf einem Upgrade auf aktuelles .NET?
Hinter Entscheidungen wie diesen steht immer ein Grund, der außerhalb des Codes selbst lebt — das damalige Budget und der Termin, Einschränkungen auf Kundenseite, die Abwägungen gegen vorhandene Ressourcen. Er ist zu groß, um in einen Kommentar zu passen, und „die Geschichte, wie wir zu dieser Entscheidung gekommen sind“ passt auch nicht bequem in ein Design-Dokument. Das Endergebnis: Der Grund überlebt nirgendwo.
2.2 Jeder Ort, an dem wir eine Entscheidung normalerweise aufbewahren, verschwindet innerhalb weniger Jahre
Wo lebt die Begründung hinter einer Designentscheidung also heute tatsächlich? Vergleichen wir die üblichen Orte.
| Wo sie aufbewahrt wird | Nach Jahren noch da? | Distanz zum Code | Findet ein Nachfolger sie? |
|---|---|---|---|
| Eine mündliche Absprache in einer Besprechung | Überlebt nicht | – | Unmöglich |
| Chat (Teams/Slack) | Scrollt weg, faktisch weg | Weit | Fast unmöglich |
| Vergraben im persönlichen Posteingang von jemandem | Weit | Weg, sobald diese Person geht | |
| Besprechungsprotokoll (ein gemeinsamer Ordner) | Überlebt, aber gemischte Qualität | Weit | Weiß nicht, in welchem Protokoll nachzuschauen ist |
| Wiki / Design-Dokument | Aktualisierungen stoppen, driftet ab | Weit | Auffindbar, aber nicht vertrauenswürdig |
| ADR (im Repository) | Überlebt direkt neben dem Code | Dasselbe Repository | Einfach docs/adr/ öffnen |
Auch Microsofts Architektur-Anleitung stellt genau diesen Punkt ausdrücklich fest: Eine nicht dokumentierte Entscheidung gerät in Vergessenheit, was dazu einlädt, dieselbe Debatte erneut zu führen und Änderungen vorzunehmen, die der ursprünglichen Absicht widersprechen.2
2.3 In der Auftragsentwicklung ist eine Vertragsgrenze eine Gedächtnisgrenze
Für die interne Entwicklung funktioniert „einfach die Person fragen“ eine Weile, aber die Auftragsentwicklung fügt zu Personalwechseln und -abgängen noch einen Anbieterwechsel hinzu. In dem Moment, in dem der Anbieter, der das System entwickelt hat, und der Anbieter, der es wartet, unterschiedliche Unternehmen sind, ist alles „Warum“, das in den Gesprächen und Chatnachrichten von jemandem lebte, vollständig verschwunden.
Auch aus vertraglicher Sicht ist es völlig normal, dass Entwicklung und Wartung getrennte Verträge und getrennte Phasen sind (wir haben diese Struktur in unserer Erklärung zur IPA-„Muster-Transaktion und -Vertrag“ behandelt). Und unter einem Geschäftsbesorgungsvertrag wird, gerade weil die beauftragte Partei die Arbeit eigenständig ausführt, ein Protokoll, das sie dem Auftraggeber zeigen kann — was entschieden wurde und wie —, zum Nachweis, der dieses Vertrauen stützt. Ein ADR hilft auf beiden Seiten.
3. Was ist ein ADR
3.1 Nygards Vorschlag — fünf Elemente und eine Zwei-Seiten-Obergrenze
ADR ist das Format, das Michael Nygard in seinem Blogbeitrag von 2011, „Documenting Architecture Decisions“, vorschlug.1 Die wichtigsten Punkte sind diese.
- Eine Datei pro Entscheidung. Fortlaufend nummerieren und eine Nummer nie wiederverwenden
- Die Datei in einem leichtgewichtigen Format wie Markdown, innerhalb des Repositorys des Projekts, aufbewahren
- Um fünf Elemente herum strukturieren: Titel / Status / Kontext / Entscheidung / Konsequenzen
- Der Status schreitet von Proposed zu Accepted fort, und bei Umkehrung zu Deprecated oder Superseded. Den alten Eintrag nie löschen
- Das Ganze auf ein bis zwei Seiten begrenzen, geschrieben in vollständigem Fließtext, den ein künftiger Entwickler wie ein Gespräch lesen kann
Trotz des Wortes „Architecture“ im Namen ist das keine Technik, die großen Systemen vorbehalten ist. Im Gegenteil, dieses minimale, feste Format funktioniert gerade am besten bei kleinen Teams ohne dedizierten Architekten und ohne jemanden, der für Dokumentation zuständig ist. ADR-Vorlagen und -Werkzeuge sind auch auf der Community-Website (adr.github.io) systematisch organisiert, was ein guter Einstiegspunkt für die Idee ist, „eine architektonisch bedeutsame Entscheidung samt ihrer Begründung und Abwägungen festzuhalten“.3
3.2 Eine Markdown-Vorlage
Hier die minimale Vorlage, die ich in kleinen Projekten verwende, treu zu Nygards Originalformat.
# ADR-NNNN: (Die Entscheidung in einem kurzen Satz formulieren)
## Status
Proposed | Accepted | Deprecated | Superseded (-> ADR-MMMM)
## Kontext
Warum wurde diese Entscheidung nötig? Schreiben Sie die technischen und
geschäftlichen Annahmen, die Einschränkungen (Budget, Termin, vorhandene
Ressourcen, die Umgebung des Kunden) und die in Betracht gezogenen
Alternativen so auf, dass ein mit der damaligen Situation nicht
vertrauter Leser noch folgen kann.
## Entscheidung
Formulieren Sie sie schlicht, im Aktiv: „Wir werden X tun.“ Ein bis drei Sätze.
## Konsequenzen
Schreiben Sie sowohl auf, was durch diese Entscheidung besser wird, als
auch, was schlechter wird (die Abwägungen). Gibt es eine Bedingung, die
künftig eine Neubewertung auslösen würde, halten Sie auch das fest.
Der entscheidende Punkt ist, unter Konsequenzen auch die Nachteile aufzuschreiben. Eine Entscheidung ohne Abwägungen ist kaum der Mühe wert, festgehalten zu werden. Auch Microsofts Anleitung betont, die Konsequenzen einer Entscheidung nicht — ob absichtlich oder versehentlich — zu verstecken, und dass ein Protokoll ohne Begründung mit der Zeit seinen Wert verliert.2
4. Was in ein ADR gehört, und was nicht
Der mit Abstand größte Grund, warum ADRs versanden, ist der Versuch, für alles eines zu schreiben. Microsofts Anleitung besagt, das Festhalten auf Dinge zu beschränken, die die Struktur des Systems oder ein wichtiges Qualitätsmerkmal betreffen und sich schwer rückgängig machen lassen.2 In eine alltägliche Faustregel übersetzt, ergibt das folgende Tabelle.
| Art der Entscheidung | Beispiel | ADR schreiben? | Warum |
|---|---|---|---|
| Eine Technologiewahl, die sich später schwer ändern lässt | Die Datenbank auf SQLite festlegen, eine Dateiübergabe für die Integration nutzen | Ja | Es später zu ändern ist teuer, und es ohne Kenntnis des Grunds anzufassen ist riskant |
| Aus mehreren vertretbaren Optionen gewählt | Einen Bericht mit einer Bibliothek statt mit COM-Automation generieren | Ja | Zu wissen, warum die andere Option verworfen wurde, erspart einem Nachfolger, die Analyse zu wiederholen |
| Eine Einschränkung gab den Ausschlag | Auf Auto-Update verzichten, weil die Umgebung des Kunden offline ist | Ja | Kann neu bewertet werden, sobald die Einschränkung wegfällt (wenn die Umgebung erneuert wird) |
| Eine Vereinbarung mit einer externen Partei | Zeichenkodierung und Layout der CSV an die Spezifikation der Gegenseite angleichen | Ja | Macht klar, dass dies eine Grenze ist, die Sie nicht einseitig ändern können |
| Eine Konvention oder einen Stil durchsetzen | Namensregeln, Formatierungseinstellungen, Reihenfolge von using-Direktiven | Nein | Eine Konfigurationsdatei wie .editorconfig plus Automatisierung reicht |
| Ein Implementierungsdetail, das sich jederzeit ändern lässt | Wie interne Klassen aufgeteilt sind, wie private Methoden organisiert sind | Nein | Der Code und das Code-Review reichen |
| Routinemäßige Betriebsarbeit | Die Patch-Version einer Bibliothek erhöhen | Nein | Der Änderungsverlauf (das Commit-Log) reicht |
Bei Unsicherheit gibt es einen einzigen Test: Würde, wer sich diesen Code in einem Jahr ansieht — einschließlich Ihr künftiges Ich —, fragen wollen, warum? Wenn ja, aufschreiben; ist es aus dem Code oder den Einstellungen selbstverständlich, nicht.
Eine weitere Falle ist, den richtigen Detailgrad in Kategorien von „welche Art Dokument“ zu denken. Die Arbeitsteilung vorab wie folgt festzulegen, nimmt das Rätselraten heraus.
| Information, die Sie bewahren möchten | Wohin sie gehört | Verhältnis zum ADR |
|---|---|---|
| Warum dieser Ansatz gewählt wurde | ADR | Der Hauptinhalt |
| Das aktuelle Architekturdiagramm / der Datenfluss | Ein (schlankes) Design-Dokument | Vom ADR aus referenziert |
| Der Inhalt einer einzelnen Änderung | Eine Commit-Nachricht / ein PR | Durch Angabe der ADR-Nummer verlinkt |
| Betriebsanleitungen | Ein Betriebshandbuch | Etwas ganz anderes (andere Leserschaft). Siehe Die Grundlagen des Schreibens eines Word-Handbuchs für Hinweise zum Schreiben |
| Ein Protokoll einer Vorfallreaktion | Ein Vorfall-Ticket / Issue | Wenn die Reaktion am Ende den Ansatz ändert, schreiben Sie dafür ein neues ADR |
5. ADRs in kleinen Auftragsprojekten betreiben
5.1 Verzeichnis und Dateibenennung
Legen Sie docs/adr/ direkt unter dem Repository-Root an und benennen Sie Dateien mit einer fortlaufenden Nummer plus einem kurzen Slug.
docs/
adr/
0001-record-architecture-decisions.md
0002-use-sqlite-for-local-storage.md
0003-excel-report-via-com-automation.md
0007-excel-report-via-openxml-library.md
Der Standardschritt ist, den allerersten Eintrag zu einem ADR über die Entscheidung zu machen, überhaupt ADRs zu verwenden. So kann ein Nachfolger die gesamte Betriebskonvention allein durch das Öffnen von docs/adr/ verstehen.
5.2 Wann geschrieben wird, und wer prüft
- Schreiben Sie es in dem Moment, in dem Sie die Entscheidung getroffen haben. Verwandeln Sie als Abschlussschritt einer Design-Diskussion das Ergebnis der Besprechung noch am selben Tag in ein ADR. Wie später behandelt, ist es ein Rezept zum Scheitern, sie zum späteren Schreiben aufzustapeln.
- Binden Sie ADRs in das Code-Review ein. Alles, was Sie prüfen, ist, ob ein Pull Request, der einen architektonischen Ansatz anfasst, eine ADR-Ergänzung oder -Aktualisierung enthält. Kein separates ADR-Genehmigungsmeeting nötig — das in das bestehende Review einzubinden, ist die realistische Antwort für ein kleines Team. ADRs unter Versionskontrolle zu halten, ist auch das, was Microsofts Anleitung empfiehlt.2
- Um eine Entscheidung umzukehren, schreiben Sie ein neues ADR und ändern den Status des alten ADR auf
Superseded, mit Querverweis zwischen beiden. Den Textkörper nie umschreiben. Einen genehmigten Eintrag nicht zu bearbeiten und die Historie durch eine Kette von Ersetzungen zu bewahren — das bedeutet es, ein ADR als Append-Only-Log zu behandeln.2
5.3 Ein ADR als Liefergegenstand, den Sie mit dem Auftraggeber teilen
In der Auftragsentwicklung empfehle ich, ADRs als Teil der Liefergegenstände mit dem Auftraggeber zu teilen. Es gibt drei Vorteile.
- Es wird zu Material für Abnahmeprüfung und Erklärung. Statt mündlich zu erklären, warum das System so strukturiert ist, können Sie einfach das ADR zeigen. Da der Auftraggeber Partei der Einschränkungen ist — Budget, Termin, Umgebung —, die eine Entscheidung antrieben, verhindert das Festhalten davon ein späteres Missverständnis.
- Es ist eine Versicherung gegen einen Anbieterwechsel. Von Auftraggeberseite macht es einen enormen Unterschied für Kosten und Risiko einer Übergabe, ob eine „Historie von Entscheidungen“ an den nächsten Anbieter übergeben werden kann. Wie Sie sich vor der Beauftragung organisieren, behandelt Worüber Sie sich vor der Auslagerung der Windows-App-Entwicklung Klarheit verschaffen sollten, aber bei der vertraglichen Festlegung, welche Dokumentation nach der Lieferung überleben soll, gehören ADRs zu den Optionen mit dem besten Aufwand-Nutzen-Verhältnis.
- Es passt gut zum Geschäftsbesorgungs-Reporting. Ein Geschäftsbesorgungsvertrag verlangt Berichte darüber, wie die Arbeit ausgeführt wurde, und ADRs können direkt als Bericht für eine Design-Phase genutzt werden.
5.4 Ein realistisches Gefühl für den Zeitaufwand
Nach meiner Erfahrung dauert das Schreiben eines Eintrags in die Vorlage 15 bis 30 Minuten. In einem kleinen Projekt fallen Entscheidungen vielleicht ein paar Mal im Monat an, sodass eine Investition von ein bis zwei Stunden im Monat jedes einzelne „Warum“ bewahrt. Verglichen mit der Zeit, die einige Jahre später für Untersuchung, erneute Debatte und Übergabe verloren geht, gibt es kaum ein Projekt, bei dem sich das nicht auszahlt.
6. Häufige Fehlermuster
| Fehlermuster | Symptom | Gegenmaßnahme |
|---|---|---|
| Zu viel schreiben | ADRs werden selbst für triviale Entscheidungen geschrieben, und die Gewohnheit brennt in drei Wochen aus | Den Umfang mit der Entscheidungstabelle aus Kapitel 4 eingrenzen. Ein paar pro Monat sind normal |
| Eine schwergewichtige Vorlage | Ein Formular mit Genehmigungsfeldern, Auswirkungsanalyse und Risikobewertung, das niemand tatsächlich ausfüllt | Zurück zu nur Nygards fünf Elementen. Eine Ein-bis-zwei-Seiten-Obergrenze1 |
| Es in einem Wiki schreiben | Aktualisierungen stoppen an einem vom Code getrennten Ort, driftet ab und verliert an Glaubwürdigkeit | Im Repository halten und gemeinsam mit dem PR prüfen |
| Zum späteren Schreiben aufstapeln | „Ich schreibe es, wenn sich die Dinge beruhigt haben“ -> die Erinnerung ist weg, und Sie können nicht mehr | Direkt nach der Entscheidung schreiben. Falls nicht möglich, live schreiben, per Bildschirmfreigabe, während der Entscheidung selbst |
| Ein früheres ADR umschreiben | Die Historie verschwindet, und Sie verlieren den Überblick, wann sich die Richtlinie geändert hat | Mit Superseded ersetzen und den Textkörper unveränderlich halten2 |
| Die Nachteile nicht unter Konsequenzen aufschreiben | Es wird zu einer bloßen Ankündigung, nutzlos für eine erneute Bewertung | Immer die Abwägungen und die Bedingungen für eine Neubewertung aufschreiben |
„Zum späteren Schreiben aufstapeln“ ist besonders eine Falle, in die man tendenziell tappt, wenn man ADRs mitten im Leben eines bestehenden Systems einführt. Statt zu versuchen, jede vergangene Entscheidung zu rekonstruieren, ist der realistische Ansatz, rückwirkend nur eine Handvoll der wichtigsten Entscheidungen aufzuschreiben, an die Sie sich noch erinnern, und von den heutigen Entscheidungen an vorwärts zu bauen. Auch bei einem bestehenden (Brownfield-)System lohnt es sich, rückwirkend festzuhalten, was Sie an vergangenen Entscheidungen noch rekonstruieren können.2
7. ADR-Beispiele aus der Praxis
Hier zwei vollständige ADRs zu Themen, die bei kleinen Windows-Business-Apps häufig vorkommen (der Inhalt ist ein verallgemeinertes Beispiel).
Das erste ist eine klassische Technologiewahl-Entscheidung: die Datenbank.
# ADR-0002: Geschäftsdaten in SQLite speichern
## Status
Accepted (2026-07-17)
## Kontext
Dieses System ist eine Desktop-App zur Lagerverwaltung für einen
einzelnen Standort. Es gibt zwei oder drei Nutzer, in der Praxis ist es
aber auf einem gemeinsam genutzten PC im Backoffice installiert und wird
im Wechsel genutzt (immer nur eine Person gleichzeitig). Der Kunde hat
kein Personal, das einen Datenbankserver vor Ort betreiben könnte, und es
gibt auch kein Budget für Serverhardware. Das Datenvolumen wird
voraussichtlich auch nach zehn Jahren Betrieb im niedrigen
dreistelligen MB-Bereich bleiben. Wir haben SQL Server Express, SQLite
und eine Access-Datei (.accdb) als Optionen erwogen. SQL Server Express
wurde ausgeschlossen, weil der Kunde keine laufende Fähigkeit hat, einen
Server nach einem Windows-Update aufzubauen und zu prüfen. Access wurde
wegen des Risikos einer Beschädigung bei gleichzeitigen Schreibzugriffen
und seines schlechten künftigen Migrationspfads ausgeschlossen.
## Entscheidung
Wir verwenden SQLite zur Datenspeicherung. Die Datenbankdatei liegt
nicht in einem gemeinsamen Ordner; sie lebt lokal auf dem Haupt-PC.
Backups werden täglich als Snapshot über VACUUM INTO erstellt und auf
dem NAS gespeichert (das Kopieren der Live-Datei bei laufender App
kommt nicht infrage, da es das Risiko eines beschädigten Backups durch
eine übersehene WAL-Datei oder ein Schreib-Rennen birgt).
## Konsequenzen
- Gut: kein Datenbankserver aufzubauen oder zu pflegen. Backups sind eine einzige SQL-Anweisung
- Gut: die Runtime kann mit der App gebündelt werden, was die Installation einfach hält
- Schlecht: Schreibvorgänge sind auf Datenbankebene gesperrt, das skaliert also nicht auf mehrere Standorte oder viele gleichzeitige Nutzer
- Schlecht: eine spätere Migration zu einer Server-Datenbank erfordert eine Datenmigration und eine Überarbeitung der Verbindungsschicht
- Diese Entscheidung neu bewerten, sobald gleichzeitige Nutzung von mehreren PCs nötig wird (dann zu einer Server-Datenbank oder einem API-basierten Design wechseln)
Das zweite ist ein Beispiel für das Umkehren einer bereits getroffenen Entscheidung. Achten Sie darauf, wie hier auch Superseded verwendet wird.
# ADR-0007: Excel-Berichte mit einer Bibliothek statt mit COM-Automation generieren
## Status
Accepted (2026-07-17) -- ersetzt ADR-0003 (Einführung von COM-Automation)
## Kontext
Es besteht die Anforderung, Rechnungen und Monatsübersichten als
Excel-Dateien auszugeben. Das wurde ursprünglich gemäß ADR-0003 mit
Excel-COM-Automation implementiert, aber ein unbeaufsichtigter
nächtlicher Batch-Job hinterließ wiederholt hängende Excel-Prozesse und
blockierte die Verarbeitung, und die Notwendigkeit einer
Office-Lizenz auf der Ausführungsmaschine wurde bei jeder
Geräteerneuerung zu einem wiederkehrenden Problem. Wir haben erwogen,
COM-Automation fortzuführen (mit Prozessüberwachung ergänzt), zu einer
Bibliothek zu wechseln, die das Open-XML-Format direkt generiert, und
Berichte in PDF umzuwandeln (eine Spezifikationsänderung). PDF wurde
ausgeschlossen, weil sich der Kunde darauf verlässt, Notizen direkt in
Excel hinzufügen zu können.
## Entscheidung
Wir stellen Berichte auf die direkte Generierung von .xlsx mit einer
Bibliothek um, ohne Abhängigkeit von Excel selbst. Die Formatierung wird
als Vorlagen-.xlsx-Datei im Repository gehalten, und die Generierung
erfolgt durch Befüllen von Zellen.
## Konsequenzen
- Gut: Excel ist in der Ausführungsumgebung nicht mehr erforderlich, und unbeaufsichtigte Läufe werden stabil
- Gut: das Problem hängender Prozesse ist strukturell beseitigt
- Schlecht: nicht alle Funktionen von Excel sind verfügbar, sodass manche bestehende Berichtsformatierung vereinfacht werden muss
- Schlecht: die bestehenden Berichte in Vorlagen zu verwandeln erfordert Überarbeitungsaufwand
- ADR-0003 wird als Superseded markiert, mit Referenz auf dieses ADR
Allein diese beiden Einträge zu lesen, beantwortet genau die Fragen, die bei einer Übergabe immer aufkommen: „warum hat dieses System keine Server-Datenbank?“ und „warum enthält der Berichtscode noch Spuren des Startens von Excel?“ Zusammen umfassen sie etwa 1.500 Zeichen und dauern weniger als eine Stunde zum Schreiben.
8. Zusammenfassung
- Was bei Wartung und Übergabe Ärger verursacht, wenn es verloren geht, ist nicht das Was, sondern das Warum. Eine nicht dokumentierte Entscheidung gerät in Vergessenheit, was dazu einlädt, dieselbe Debatte erneut zu führen und Änderungen vorzunehmen, die der ursprünglichen Absicht widersprechen.2
- Ein ADR ist ein leichtgewichtiges Protokollformat: eine Entscheidung pro Datei, fünf Elemente, höchstens ein bis zwei Seiten. Nygards Originalform funktioniert unverändert für Entwicklung im kleinen Maßstab.1
- Schreiben Sie nur Entscheidungen auf, die sich schwer ändern lassen, echte Alternativen hatten oder von einer Einschränkung entschieden wurden. Überlassen Sie Konventionen und Formatierung der Automatisierung — sie sind außerhalb des Umfangs eines ADR.2
- Halten Sie sie in
docs/adr/und prüfen Sie sie gemeinsam mit dem Pull Request. Überschreiben Sie eine Entscheidung nie — ersetzen Sie sie über Superseded — und halten Sie die Historie unveränderlich.12 - In der Auftragsentwicklung wird ein ADR zu einem auch für den Auftraggeber wertvollen Liefergegenstand, der als Abnahmeprüfungsdokumentation und als Übergabedokument bei Anbieterwechseln dient.
- Fünfzehn bis dreißig Minuten pro Eintrag. Beginnen Sie damit, eines für Ihre allernächste Designentscheidung zu schreiben — und arbeiten Sie an einem bestehenden System, beginnen Sie damit, rückwirkend nur eine Handvoll der wichtigsten Entscheidungen aufzuschreiben, an die Sie sich noch erinnern.
Verwandte Artikel
- Wie sollte ein Vertrag für Entwicklung und laufende Wartung strukturiert sein? — Die Wahl zwischen Geschäftsbesorgung und Werkvertrag, Lehren aus der IPA-„Muster-Transaktion und -Vertrag“
- Worüber Sie sich vor der Auslagerung der Windows-App-Entwicklung Klarheit verschaffen sollten
- Die Grundlagen des Schreibens eines Word-Handbuchs — Schlechte Beispiele und wie man sie behebt
Verwandte Beratungsbereiche
Die KomuraSoft LLC (合同会社小村ソフト) übernimmt die Unterstützung von Teams bei der Einführung von ADRs als Teil eines Design-Reviews, die Bestandsaufnahme und Dokumentation der Designentscheidungen hinter einem bestehenden System sowie den Aufbau einer Wartungseinrichtung mit Blick auf Übergaben und Anbieterwechsel.
- Technische Beratung & Design-Review
- Windows-App-Entwicklung
- Änderung & Wartung bestehender Windows-Software
- Kontakt
Referenzlinks
-
Michael Nygard, Documenting Architecture Decisions. Die Ursprungsquelle für ADRs (2011). Zu den fünf Elementen — Titel/Kontext/Entscheidung/Status/Konsequenzen —, dem Statusfortschritt von Proposed über Accepted zu Deprecated/Superseded, der Ein-bis-zwei-Seiten-Länge, dem Aufbewahren als fortlaufend nummerierte Dateien im Repository und dem Bewahren alter Entscheidungen über Superseded statt Löschen. ↩ ↩2 ↩3 ↩4 ↩5 ↩6
-
Microsoft Learn, Maintain an architecture decision record (ADR). Anleitung aus dem Azure Well-Architected Framework. Dazu, ein ADR-Log als Append-Only zu behandeln und einen genehmigten Eintrag nie zu bearbeiten; eine Entscheidung bei Änderung durch einen neuen Eintrag zu ersetzen und beide querzuverweisen; den Umfang auf Entscheidungen zu beschränken, die die Systemstruktur oder ein wichtiges Qualitätsmerkmal betreffen und sich schwer rückgängig machen lassen; Kontext, Begründung, Abwägungen und Status (Proposed/Accepted/Superseded) einzuschließen; dazu, dass nicht dokumentierte Entscheidungen in Vergessenheit geraten und erneute Debatten oder der ursprünglichen Absicht widersprechende Änderungen provozieren; und dazu, dass es sich lohnt, vergangene Entscheidungen selbst für eine bestehende Arbeitslast rückwirkend festzuhalten. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13
-
adr.github.io, Architectural Decision Records. Die ADR-Community-Website. Zu den Definitionen einer architektonischen Entscheidung (AD) und einer architektonisch bedeutsamen Anforderung (ASR), dazu, dass ein ADR eine einzelne Entscheidung samt Begründung, Abwägungen und Konsequenzen festhält, und zur verfügbaren Sammlung von Vorlagen und Werkzeugen. ↩
Verwandte Artikel
Aktuelle Artikel mit denselben Schlagwörtern führen zu verwandten Themen weiter.
Incident Response endet nicht mit der Wiederherstellung ── Eine Postmortem-Vorlage (Rückfallprävention) für kleine Entwicklungsteams
Einen Vorfall als erledigt zu betrachten, sobald er behoben und man sich entschuldigt hat, garantiert, dass er sich wiederholt. Dieser Ar...
Vergessen Sie nicht zu entscheiden, „wie viele Sekunden schnell genug sind“ ── Nichtfunktionale Anforderungen mit IPAs Non-Functional Requirements Grade ordnen
Streitigkeiten wie „es ist zu langsam“ oder „mit dieser Ausfallreaktion haben wir nicht gerechnet“ lassen sich meist auf nichtfunktionale...
Wenn Sie ein System ohne Quellcode und ohne Dokumentation übernehmen — Ein praktisches Playbook, um es am Laufen zu halten
Ein praktisches Playbook für den Beginn von Betrieb und Wartung eines Geschäftssystems ohne Quellcode und ohne Spezifikationen. Behandelt...
Wenn man eine Windows-App besser nicht ins Web migriert: Entscheidungstabelle und die pragmatische Lösung der Aufteilung
Der Wunsch, interne Windows-Anwendungen ins Web zu migrieren, nimmt stetig zu. Doch bei Apps mit Gerätekopplung, lokaler Dateiverarbeitun...
Windows-App-Outsourcing und Auftragsentwicklung: Was Sie vor der Beauftragung klären sollten
Bevor Sie die Entwicklung einer Windows-App outsourcen oder in Auftrag geben, sollten Sie folgende Punkte klären: Überarbeitung bestehend...
Verwandte Themen
Diese Seiten ordnen den Artikel in einen größeren Leistungs- und Entscheidungskontext ein.
Technische Windows-Themen
Portal zu Windows-Entwicklung, Fehleranalyse und der Nutzung bestehender Assets.
Leistungen zu diesem Thema
Dieser Artikel ist direkt mit den folgenden Leistungen verbunden.
Technische Beratung und Design-Review
Klärung von Änderungsstrategie, Entwurf und Umgang mit bestehenden Assets.
Häufige Fragen
Fragen, die in Beratungen zu diesem Artikelthema häufig gestellt werden.
- Was ist ein ADR (Architecture Decision Record)?
- Es ist ein Dokument, das eine einzelne Entscheidung mit Auswirkung auf die Struktur eines Softwaresystems in einer Datei festhält, in einem kurzen, festen Format: Titel / Status / Kontext / Entscheidung / Konsequenzen. Michael Nygard schlug dieses leichtgewichtige Format 2011 vor; die Grundregeln sind, jedes auf höchstens ein bis zwei Seiten zu beschränken und es als Markdown im selben Repository wie den Code zu committen. Anders als ein umfassendes Design-Dokument ist es darauf spezialisiert festzuhalten, warum eine bestimmte Wahl getroffen wurde und welche Alternativen verworfen wurden.
- Was sollte ich in einem ADR festhalten, und was kann ich weglassen?
- Aufschreibenswert sind: Entscheidungen, die sich später schwer ändern lassen (die Wahl einer Datenbank oder einer Kommunikationsmethode, das Format einer externen Integration usw.), Entscheidungen, die zwischen mehreren gleichermaßen vertretbaren Optionen getroffen wurden, und Entscheidungen, bei denen eine Einschränkung — Budget, Termin, vorhandene Ressourcen — den Ausschlag gab. Umgekehrt brauchen Dinge, die ein Werkzeug oder eine Konvention mechanisch durchsetzen kann, wie Namensregeln oder Formatierungseinstellungen, oder Dinge, die sich leicht ändern lassen und aus dem Lesen des Codes selbstverständlich sind, keines. Sind Sie unsicher, verwenden Sie diesen Test: „Würde ich, ein Jahr später, fragen wollen, warum?“
- Wenn ich eine frühere Entscheidung ändern möchte — ist es in Ordnung, das alte ADR umzuschreiben?
- Nein — schreiben Sie es nicht um; fügen Sie ein neues ADR hinzu, das es ersetzt. Ändern Sie den Status des alten ADR auf Superseded, fügen Sie eine Referenz auf das neue ADR hinzu und lassen Sie seinen Textkörper unangetastet. Microsofts Anleitung empfiehlt ebenso, ein ADR-Log als Append-Only zu behandeln und einen genehmigten Eintrag nachträglich niemals zu bearbeiten. So wird die Historie selbst — wann und warum sich die Richtlinie geändert hat — zu einem eigenständigen Übergabedokument.
- Wenn wir bereits ein Design-Dokument haben — ist ein ADR dann überflüssig?
- Sie spielen unterschiedliche Rollen. Ein Design-Dokument zeigt, wie die Struktur aktuell ist, bewahrt aber meist nicht, warum diese Struktur gewählt wurde und was verworfen wurde. Ein umfassendes Design-Dokument neigt zudem dazu, nach einigen Jahren nicht mehr aktualisiert zu werden und vom Code abzudriften. Ein ADR erfordert nur das Anhängen weniger hundert Zeichen pro Entscheidung, ist also viel weniger anfällig dafür, zu veralten — selbst nachdem das Design-Dokument veraltet ist, überlebt die Begründung hinter jeder Entscheidung eigenständig. Für Entwicklung im kleinen Maßstab ist ein realistischer Aufbau, das detaillierte Design-Dokument schlank zu halten und es mit ADRs zu kombinieren.
Autorenprofil
Profilseite des Artikelautors.
Go Komura
Geschäftsführer von KomuraSoft LLC
Spezialisiert auf Windows-Softwareentwicklung, technische Beratung und Fehleranalyse, insbesondere bei bestehenden Systemen und schwer reproduzierbaren Störungen.