Arc42, ADRs und Architekturentscheidungen
Mit Arc42 und ADRs dokumentieren Teams Architekturentscheidungen schlank und nachvollziehbar. So bleiben Kontext, Optionen und Folgen auch Monate später klar.
Architekturdokumentation hat in vielen Teams einen schlechten Ruf. Nicht ganz zu Unrecht.
Oft gibt es entweder zu wenig Dokumentation oder die falsche: lange Dokumente, die viel Aufwand kosten, aber im Alltag niemandem helfen. Nach ein paar Monaten sind sie veraltet und verlieren jede Relevanz.
Das bedeutet aber nicht, dass Architekturarbeit ohne Dokumentation auskommt. Im Gegenteil: Gerade in wachsenden Projekten ist nachvollziehbare Entscheidungsdokumentation ein echter Beschleuniger.
Weiterführende Artikel zu diesem Thema: Clean Architecture Dotnet und Cloud Migration Vorbereiten.
Warum Teams Architekturentscheidungen dokumentieren sollten
In fast jedem längeren Projekt tauchen dieselben Fragen wieder auf:
- Warum haben wir uns für diese Plattform entschieden?
- Weshalb wurde Modul A nicht direkt mit System B gekoppelt?
- Warum gibt es diesen Service überhaupt?
- Weshalb ist Deployment oder Security auf diese Weise aufgebaut?
Wenn diese Fragen nur im Kopf einzelner Personen beantwortet werden können, entsteht Abhängigkeit. Sobald Teammitglieder wechseln oder ein Projekt in eine neü Phase geht, wird aus fehlender Dokumentation schnell Reibung.
Was Arc42 und ADRs gut leisten
Ich halte die Kombination aus Arc42 und Architecture Decision Records für sehr praktikabel.
Arc42
Arc42 hilft, die Architektur strukturiert zu beschreiben:
- Kontext
- Bausteine
- Laufzeitsicht
- Verteilungssicht
- Risiken
- Qualitätsziele
Das ist besonders hilfreich, wenn Teams ein gemeinsames Gesamtbild brauchen.
ADRs
ADRs sind deutlich fokussierter. Sie dokumentieren einzelne Architekturentscheidungen mit Kontext, Optionen und Begründung.
Typische ADR-Themen sind:
- Azure oder AWS
- Monolith oder Microservices
- RAG ja oder nein
- Kubernetes oder einfacheres Hosting
- zentrale Integrationsschicht ja oder nein
Gerade diese punktülle Entscheidungsdokumentation ist im Alltag oft besonders wertvoll.
Was gute Dokumentation ausmacht
Gute Architekturdokumentation ist nicht vollständig, sondern nützlich.
Sie sollte:
- konkrete Entscheidungen nachvollziehbar machen
- Annahmen und Risiken sichtbar halten
- neün Teammitgliedern Orientierung geben
- bei Änderungen als Referenz dienen
Was sie nicht sein sollte:
- ein zweites Lastenheft
- eine Folienablage in Textform
- ein Dokument, das nur für Audits gepflegt wird
Wann Dokumentation besonders wichtig wird
Dokumentation ist nicht in jeder Projektphase gleich wichtig. Besonders relevant wird sie, wenn:
- mehrere Teams beteiligt sind
- Verantwortung übergeben wird
- Architekturfragen strittig oder teür sind
- Integrationen oder Plattformentscheidungen langfristig wirken
- die Delivery-Geschwindigkeit steigt und Entscheidungen nicht ständig neu diskutiert werden sollen
Das trifft gerade auf Cloud-, Integrations- und Plattformprojekte sehr häufig zu.
Die häufigsten Fehler
1. Alles dokumentieren wollen
Dann entsteht ein schwergewichtiges Konstrukt, das niemand aktüll halten kann.
2. Nichts Entscheidendes dokumentieren
Dann fehlen später genau die Begründungen für teure oder weitreichende Architekturentscheidungen.
3. Dokumentation nicht im Delivery-Prozess verankern
Wenn ADRs oder Architekturdokumente nur sporadisch und außerhalb der eigentlichen Umsetzung gepflegt werden, verlieren sie schnell an Relevanz.
Ein pragmatischer Minimalansatz
Für viele Teams reicht bereits:
- eine kompakte Arc42-Struktur als Überblick
- ADRs für zentrale Leitentscheidungen
- regelmäßige Aktualisierung bei relevanten Änderungen
Dieser Ansatz ist leicht genug für den Alltag und gleichzeitig stark genug, um Architekturwissen nicht zu verlieren.
Warum das Delivery verbessert
Gute Entscheidungsdokumentation macht Delivery schneller, weil:
- weniger Grundsatzdiskussionen wiederholt werden
- neü Teammitglieder schneller anschlussfähig sind
- Änderungen besser eingeordnet werden können
- Risiken früher sichtbar werden
Gerade in Projekten mit Modernisierung oder Plattformaufbau ist das ein echter Vorteil. Ein praktisches Beispiel dafür findet sich auch in Cloud-Migration vorbereiten: Welche Architekturfragen vor dem ersten Ticket geklärt sein sollten.
Auch bei Architekturumbauten wie in Von modularen Monolithen zu Microservices: Wie man sauber migriert, ohne das Team zu überfordern zeigt sich sehr schnell, wie wertvoll nachvollziehbare Leitentscheidungen im Alltag wirklich sind.
Fazit
Architekturdokumentation sollte Teams helfen, nicht beeindrucken. Arc42 und ADRs sind dafür ein sehr brauchbarer Rahmen, wenn sie pragmatisch eingesetzt werden.
Nicht die Menge der Dokumentation zählt, sondern ob wichtige Entscheidungen verständlich, auffindbar und aktüll genug bleiben, um das Projekt zu unterstützen.
Sie möchten Architekturentscheidungen in Ihrem Projekt nachvollziehbar und handhabbar dokumentieren? Sprechen Sie uns an - wir helfen dabei, eine leichte, aber belastbare Dokumentationsstruktur aufzusetzen.
Weiterführende Beiträge
Wenn dieses Thema für Ihre Roadmap relevant ist, sind diese Beiträge der nächste sinnvolle Schritt: