Decision Log Tooling

Systemzweck

In der Systemtheorie ist fehlendes Wissen über frühere Entscheidungen eine häufige Ursache für problematisches Re-Engineering (Chesterton's Fence: Reiße keinen Zaun ab, bevor du nicht weißt, warum er gebaut wurde). Wenn ein neuer Lead Developer fragt, warum ein System SOAP statt REST nutzt, sollte die Antwort nicht aus Vermutungen bestehen. Ohne Kontext besteht das Risiko, frühere Randbedingungen zu übersehen. Architekten verlassen Firmen, und mit ihnen geht oft Entscheidungswissen verloren. Decision Log Tooling automatisiert das Archivieren der technischen Trade-offs direkt in der Codebase.

Mechanik des Werkzeugs

Das wichtige Kern-Format ist das Architecture Decision Record (ADR), geprägt von Michael Nygard. Formale Tools (wie adr-tools oder log4brains) generieren winzige Markdown-Dateien fortlaufend direkt in dein Git-Repository (Ordner: docs/adr/). Ein ADR zwingt den Architekten zu fünf konsequent simplen Blöcken:

1.Titel: ("Wechsel von MongoDB zu PostgreSQL")

2.Status: (Vorgeschlagen / Akzeptiert / Veraltet)

3.Context: ("Unsere Dokumentengröße sprengt RAM-Limits")

4.Decision: ("Wir erzwingen Relationale Speicherung")

5.Consequences: ("Positive: Keine OOM-Crashes. Negative: Alle Devs müssen SQL neu lernen").

Architektur-Einsatz

Decision Tooling ist der Anker der "Explicit Tradeoff Policies". Wenn der Chief Architect festlegt, dass ohne ein "Accepted ADR" kein Infrastruktur-Terraform-Skript in Produktion wandern darf, ändert er die Spielregeln des Systems (High Leverage Point). Entwickler können sich nicht länger intuitiv ("Aus dem Bauch heraus") in Meetings zu Architekturentscheidungen hinreißen lassen, sondern müssen ihre physikalischen Annahmen vor der gesamten Firma schriftlich im Log rechtfertigen.

Grenzen und Gefahren

ADRs mutieren schnell zu nutzlosem Mikromanagement-Bürokratie. Wenn Entwickler anfangen, "ADR 0534: Wir nutzen die for-Schleife anstatt while für Listen" zu loggen, bluten die Repositories im dem Prozessen (Noise) aus. Ein ADR ist ein System-Dokument. Es wird nur geschrieben, wenn die Entscheidung eine Eigenschaft (Qualität, "-ility") des Systems verbiegt. ("Wir opfern Performance zugunsten von Security"). Kleinigkeiten gehören in Pull-Request-Kommentare, nicht in das Architektur-Log.

Diagramm

Abgrenzung

Confluence/Wikis sind Dokumentations-Friedhöfe (Weit weg vom Code). Causal Loop Tools (Kumu) kartografieren das Jetzt. Decision Log Tooling (ADRs) sichern die Zeitachse. Sie liegen direkt neben dem Code (Git), reisen mit dem Code in Versionen mit und vergehen, wenn der Code vergeht (Docs-as-Code Methode).

Entscheidungs- und Praxisleitfaden

Mache ADRs unumkehrbar in der System-Pipeline. Nutze Tools, die im CI/CD-Prozess einen markdown-linter ausführen. Wenn ein Entwickler einen Pull-Request einreicht, der eine neue Cloud-Datenbank instanziiert, weigert sich der Build-Server strikt zu kompilieren, wenn nicht im selben Commit eine Datei namens 0042-use-cloud-database.md im ADR-Ordner liegt. Zwinge das Tooling in den physikalischen Atmungsprozess der Entwickler.

Quellen

Michael Nygard — Documenting Architecture Decisions (Blog, 2011)

adr-tools — CLI for Architecture Decision Records (GitHub)

Log4brains — Architecture Knowledge Base (GitHub)