In der heutigen Softwareentwicklung treffen Teams kontinuierlich technologische Entscheidungen – sei es bei der Wahl eines Frameworks, dem Entwurf einer Schnittstelle oder der Definition von Sicherheitsmechanismen. Oft sind diese Entscheidungen maßgeblich für den weiteren Projekterfolg, doch zu selten werden sie strukturiert dokumentiert. Genau hier kommen Architecture Decision Records (ADR) ins Spiel.
Ein ADR ist die Dokumentation von technologischen Entscheidungen, die eine signifikante Bedeutung für aktuelle und zukünftige Projektumsetzungen haben. Dabei geht es nicht nur um das Was der Entscheidung, sondern auch um das Warum – inklusive des Entscheidungsprozesses und der beteiligten Personen oder Rollen.
ADRs schaffen Transparenz, fördern ein gemeinsames Verständnis im Team und helfen, technische Entscheidungen auch nach Monaten oder Jahren noch nachvollziehen zu können. In diesem Blogbeitrag schauen wir uns an, wie ADRs funktionieren, warum sie so wertvoll sind und wie man sie im Projektalltag effektiv einsetzen kann. Zur Veranschaulichung haben unsere Xperten ein konkretes Beispiel erarbeitet.
Wann lohnt sich der Einsatz von ADRs?
Architecture Decision Records sind besonders dann hilfreich, wenn Entscheidungen getroffen werden, die langfristige Auswirkungen auf die Architektur oder die Zusammenarbeit im Team haben. Typische Einsatzszenarien sind:
- Grundlegende Technologieentscheidungen
Wenn grundlegende technologische Weichen gestellt werden, sollte die Entscheidung gut dokumentiert sein.- Beispiel: Entscheidung für React anstelle von Angular als Frontend-Framework oder die Einführung von Kubernetes als Orchestrierungsplattform.
- Beispiel: Entscheidung für React anstelle von Angular als Frontend-Framework oder die Einführung von Kubernetes als Orchestrierungsplattform.
- Teamübergreifende Entwicklungen und Schnittstellen
Bei Entscheidungen, die mehrere Teams betreffen, ist ein gemeinsames Verständnis essenziell – ADRs fördern dieses.- Beispiel: Ein größeres Feature, an welchem mehrere Teams arbeiten, wird geplant. Welches Team setzt welchen Feature-Bestandteil um? Welche Schnittstellen zur Datenübergabe und Umsetzung der technischen Prozesse werden benötigt?
- Beispiel: Ein größeres Feature, an welchem mehrere Teams arbeiten, wird geplant. Welches Team setzt welchen Feature-Bestandteil um? Welche Schnittstellen zur Datenübergabe und Umsetzung der technischen Prozesse werden benötigt?
- Festlegung technischer Standards und Konventionen
Technische Standards und Konventionen, die projektweit gelten, sollten nachvollziehbar festgehalten werden.- Beispiel: Entscheidung für die API-Entwicklung basierend auf OpenAPI inkl. Code-Generierung
- Beispiel: Entscheidung für die API-Entwicklung basierend auf OpenAPI inkl. Code-Generierung
- Unsicherheit im Team oder fehlende Erfahrung Gibt es im Team unterschiedliche Ansichten oder fehlt die Erfahrung, schafft ein ADR Struktur im Entscheidungsprozess. Er hilft dabei, Unsicherheiten zu klären und externes Know-how einzubinden.
- Beispiel: Ein modernes und sicheres Authentifizierungsframework soll das veraltete Framework vollständig ersetzen. Es sind vielfältige Anwendungsfälle (Authentifizierung und Autorisierung) zu unterstützen, die im alten Framework oft nur unzulänglich abgedeckt waren.
Aufbau eines ADR
1. Problembeschreibung
Am Anfang steht eine klar formulierte Problemstellung. Sie bildet die Grundlage für alle weiteren Überlegungen und sollte sowohl fachliche als auch technische Aspekte berücksichtigen.
Ein vollständiger Problemaufriss enthält idealerweise:
- Die geschäftlichen Ziele (z. B. Kostenreduktion, Skalierbarkeit, Time-to-Market)
- Die technischen Anforderungen (z. B. Performance, Wartbarkeit, Sicherheit)
- Funktionale und nicht-funktionale Anforderungen
2. Stakeholder identifizieren
Ein oft unterschätzter Schritt – dabei ist er entscheidend für die Qualität und Akzeptanz der Entscheidung. Stakeholder sollten frühzeitig eingebunden werden, um Anforderungen, Perspektiven und potenzielle Risiken vollständig zu erfassen.
Vorteile:
- Die Qualität der Lösung steigt durch breit abgestimmtes Fachwissen.
- Die Akzeptanz wächst, wenn betroffene Personen aktiv in den Prozess eingebunden sind.
3. Rahmenbedingungen festhalten
Der Lösungsraum wird durch technische und organisatorische Rahmenbedingungen begrenzt. Diese sollten frühzeitig dokumentiert werden, um realistische und praktikable Optionen zu entwickeln.
Typische Rahmenbedingungen sind:
- Technische Vorgaben: z. B. vorgeschriebene Frameworks, bestehende Systeme, Abhängigkeiten.
- Organisatorische Einschränkungen: z. B. feste Zeitpläne, begrenzte Ressourcen, feste Teamzuschnitte.
4. Entscheidung
Am Ende jedes ADRs steht die dokumentierte Entscheidung – sie ist das Herzstück des Dokuments. Nach der Analyse der Optionen oder der Validierung eines Lösungsansatzes wird hier klar festgehalten, welcher Weg eingeschlagen wird und warum.
Was sollte die Entscheidungssektion enthalten?
- Die gewählte Option: möglichst konkret beschrieben (z. B. „Einführung von Tool X“, „Beibehaltung der bisherigen Architektur“)
- Begründung: auf Basis der Vergleichskriterien, Stakeholderbeiträge und Anforderungen
- (Optional) Verworfenene Alternativen: Wenn Variante A oder B diskutiert wurden, kann hier festgehalten werden, warum andere Optionen nicht gewählt wurden
- Datum und Status: damit nachvollziehbar ist, wann und von wem die Entscheidung getroffen wurde (z. B. „Entschieden am 10.03.2025 – Status: Accepted“)
Diese letzte Sektion sorgt für Verbindlichkeit und Nachvollziehbarkeit. Sie schafft Klarheit für das Team, aber auch für alle, die zu einem späteren Zeitpunkt mit den Auswirkungen der Entscheidung arbeiten.
Gerade im Fall späterer Änderungen oder Projektweiterentwicklungen bietet die dokumentierte Entscheidung eine wertvolle Referenz: Warum wurde damals so entschieden? Welche Alternativen wurden erwogen – und warum nicht umgesetzt? Beispiel-ADR
1. Einführung und Ziele
1.1 Aufgabenstellung
Für die Umsetzung des Projekts „Energiehandel“ soll ein zeitgemäßes und leistungsfähiges UI Framework ausgewählt werden, um eine browserbasierte User-Oberfläche umzusetzen. Die UI soll im MVP noch eine verhältnismäßig geringe Komplexität aufweisen und in späteren Ausbaustufen eine mittlere Komplexität erreichen.
Die UI kommuniziert über eine REST API mit dem Backend. Es werden im MVP 20 und in späteren Ausbaustufen bis zu 100 Nutzende erwartet. Die UX-Anforderungen an die UI sind im normalen Businessbereich; allerdings soll die UI die im Backend verfügbaren und sich ständig ändernden Energiepreise nahezu in Echtzeit anzeigen.
1.2 Qualitätsziele
Umsetzung vorrangig mit eigenen Entwickelnden, ergänzt durch Freelancer:
Die Umsetzung soll überwiegend durch die eigene Belegschaft erfolgen. Zum Ausgleich von Auslastungsspitzen und zur Abdeckung aller benötigten Kompetenzen ist der Einsatz von Freelancern geplant.
Echtzeit-Fähigkeiten:
Die UI soll bereits im MVP Informationen des Backends in Echtzeit anzeigen und aktualisieren. Die Echtzeit-Fähigkeiten sind auch im weiteren Projektverlauf sicherzustellen, wenn die Komplexität der UI, des Backends sowie die Datenmengen steigen.
Moderne UX, wie sie im heutigen Business-Umfeld erwartet wird:
UX und UI sollen zweckmäßig, aber dennoch modern und zeitgemäß sein. Sie wird von „Expert Users“ im Geschäftsumfeld benutzt werden.
2. Stakeholder
| Rolle | Kontakt | Motivation |
|---|---|---|
| Product Owner | Sarah | Möchte dem Kunden eine qualitativ ansprechende Umsetzung in der zugesagten Zeit übergeben. Möchte mit einem Team aus motivierten Entwickelnden zusammenarbeiten und keine zu großen Aufwände bei der Teamzusammenstellung haben. |
| Angular Senior Dev | Albert | Ist überzeugt davon, dass das Projekt mit Angular umgesetzt werden kann. Möchte die Angular-Position gut vertreten, hat derzeit aber ausreichend zu tun (was auch für die anderen Angular Devs zutrifft). |
| React Senior Dev | Tim | Ist überzeugt davon, dass das Projekt mit React umgesetzt werden kann. Möchte die React-Position gut vertreten und sieht mittelfristig Bedarf an einem neuen Projekt für sich und die anderen React Devs. |
| HR | Amrita | Möchte das Projekt personell für die initiale Phase von 6–12 Monaten gut abdecken und denkt auch an die längerfristige Betreuung von 3–5 Jahren. Möchte am Markt bei Bedarf eine gute Auswahl an Freelancern für die benötigten Technologien haben. |
Abgrenzung, keine Stakeholder
- Kunde: Die Technologie ist dem Kunden relativ egal, wesentliche Interessen sind durch PO abgedeckt.
- Architekten: Sehen die technisch wesentlichen Positionen ausreichend durch Albert und Tim abgedeckt.
3. Rahmenbedingungen
3.1 Technisch
- Kommunikation mit dem Backend erfolgt über REST APIs
- Zu unterstützende Browser: Chrome + Mozilla
- Verwendung der firmeninternen Angular/React Component Library, soweit möglich
3.2 Organisatorisch
- Fertigstellung MVP in 5 Monaten
- Zeitnahe Umsetzung zweier Ausbaustufen bei MVP-Erfolg; Dauer jeweils ~6 Monate
- Entwicklungsteam (nur Frontend) 3 Personen, max. 4 bei Auslastungsspitzen
4. Lösungsstrategie
4.1 Lösungsoptionen
Im Laufe des iterativen Prozesses gab es von einer Entwicklerin den Vorschlag, Svelte einzusetzen. Daher wurde es als dritte Option in den ADR mitaufnommen.
| Kriterium | Angular | React | Svelte |
|---|---|---|---|
| Personal intern | 8 Entwickelnde | 6 Entwickelnde | 2 Entwickelnde |
| Personal extern | Es gibt sehr viele Freelancer, die Angular können | Es gibt sehr viele Freelancer, die React können | Es gibt einige Freelancer, die Svelte können |
| Moderne, ansprechende UX im Business-Umfeld | umsetzbar | umsetzbar | umsetzbar |
| Echtzeitfähigkeiten | umsetzbar (Socket-IO Library, Observables) | umsetzbar (Server-sent events, Websockets) | umsetzbar (Server-sent events, Websockets) |
| Verfügbarkeit Personal intern | Aktuell hohe Auslastung; keine Änderung in den nächsten 6 Monaten erwartbar | Aktuell mittlere-hohe Auslastung; 3 Entwickelnde brauchen in 3–4 Monaten voraussichtlich ein neues Projekt | Die Svelte-Entwickelnden sind aktuell in Projekten, aber wenigstens eine Person könnte mit 4-Wochen-Frist aus dem Projekt rausgehen |
| Technologie-Innovation | Angular ist etabliert, aber nicht wirklich innovativ | React ist etabliert, aber nicht wirklich innovativ | Svelte hat den steilsten Anstieg beim Overall Rating von UI-Frameworks in den letzten beiden Jahren. Aufbau von Wissen ist empfehlenswert. |
4.2 Entscheidung
Das Projekt wird mit React umgesetzt. Es stehen intern ausreichend Entwickelnde zur Verfügung, der Freelancer-Markt ist gut aufgestellt, und alle Anforderungen sind zuverlässig erfüllbar.
Alternativen:
Angular wurde verworfen aufgrund fehlender interner Verfügbarkeit.
Svelte wurde als innovative Option diskutiert, aber mangels Know-how und begrenzter Marktreife nicht gewählt.
Ausblick:
Zwei Entwickelnde sollen sich in den nächsten 3–6 Monaten eine Svelte-Weiterbildung mit wenigstens mittlerer Tiefe (2-3 Tage) absolvieren.
Status:
Entschieden am 10.03.2025 – Status: Accepted
ADR-Varianten
In der Praxis haben sich verschiedene Herangehensweisen an die Erstellung von ADRs etabliert. Unsere Xperten stoßen vor allem auf zwei Varianten:
Variante A: Optionen analysieren und vergleichen
Diese Variante kommt zum Einsatz, wenn es mehrere realistische Lösungswege gibt. Ziel ist es, eine fundierte Entscheidung auf Basis definierter Anforderungen zu treffen – technisch und wirtschaftlich.
Vorgehen:
- Realistische Optionen werden systematisch gesammelt
- Jede Option wird hinsichtlich Vor- und Nachteilen bewertet
- Vergleichskriterien leiten sich direkt aus der Problembeschreibung und den Rahmenbedingungen ab
- Häufig werden die Ergebnisse in Tabellenform dargestellt
Besonderheit:
Der Entscheidungsprozess ist iterativ. Stakeholder bringen ihre Perspektiven und ihr Fachwissen ein, um die Optionen zu schärfen und eine fundierte Entscheidung zu ermöglichen.
Variante B: Fokus auf Machbarkeit (Proof-like Approach)
Manche Entscheidungen betreffen so komplexe oder neuartige Themen, dass zunächst nur eine Lösungsidee im Detail erarbeitet wird. Das Ziel ist, diese einem „Community Review“ zu unterziehen, um grundlegende Schwächen oder Risiken frühzeitig aufzudecken.
Vorgehen:
- Eine vielversprechende Lösung wird tiefgehend ausgearbeitet
- Der Fokus liegt auf der technischen Machbarkeit
- Stakeholder prüfen die Option gezielt auf K.-o.-Kriterien
- Verbesserungen erfolgen durch gemeinsames Review, nicht durch den Vergleich mit Alternativen
Besonderheit:
Scheitert die Variante im Review, muss eine alternative Lösung erarbeitet werden – was zusätzliche Zeit kosten kann. Deshalb ist ein strukturierter Reviewprozess hier besonders wichtig.
Unsere Empfehlungen für den Prozess
1. Schnell starten & früh präsentieren
- Die initiale Vorstellung des ADR kann geschehen, wenn die Problemstellung und eine erste Liste der Stakeholder bekannt sind. Der Zeitaufwand sollte nicht mehr als 30-60 Minuten betragen
2. Iterative Phase fokussiert und zielgerichtet durchführen
- Während der iterativen Phase erweitern sich häufig die Perspektiven: Neue Stakeholder, zusätzliche Lösungsansätze und weitere Pro- und Kontra-Argumente kommen hinzu.
- Dieser Input ist zentraler Bestandteil des ADR – dennoch lohnt es sich hier, auf Effizienz zu achten.
- Maximal drei Iterationen und eine Iteration pro Woche sind eine gute Empfehlung, um den ADR innerhalb eines Monats zur Entscheidung zu bringen.
Risiken des ADR
Wie jedes Werkzeug bringt auch ein ADR potenzielle Herausforderungen mit sich. Wird der Prozess zu langwierig oder zu detailliert geführt, kann er als bürokratisch empfunden werden und Entscheidungen unnötig verzögern. Umso wichtiger sind ein klarer Fokus und ein gut strukturierter Ablauf.
Referenzen IT Sonix
In einem unserer großen Energieprojekte Energieprojekte sind ADRs inzwischen gelebte Praxis. Sie helfen dabei, technische Innovationen und Lösungsansätze strukturiert, transparent und in hoher Qualität zu dokumentieren und im Team zu diskutieren. Ein Großteil der Entwickelnden ist regelmäßig in Reviews eingebunden; einige erstellen auch selbst ADRs. So entstehen fundierte Entscheidungen, die im Projekt nachvollziehbar und langfristig tragfähig sind. Besonders beim Onboarding neuer Teammitglieder oder bei späteren Architekturentscheidungen zeigt sich der Mehrwert: Die Hintergründe technischer Entscheidungen bleiben auch nach Monaten oder Jahren nachvollziehbar.
Fazit
ADRs sind kein Selbstzweck, sondern ein wirkungsvolles Werkzeug, um technische Entscheidungen nachvollziehbar und teamübergreifend zu dokumentieren. Richtig eingesetzt, fördern sie Qualität, Transparenz und Entscheidungsstärke im Projektalltag – ohne dabei den Prozess unnötig zu verlangsamen. Auch wenn der Einstieg etwas Disziplin erfordert: Der langfristige Nutzen für Kommunikation, Wartbarkeit und Zusammenarbeit ist die Mühe in jedem Fall wert.