Architekturdokumentation effektiv gestalten: Balance zwischen Stabilität und Agilität

Diese Frage stellt sich fast jedes Software-Team, das in einer agilen Welt versucht, eine stabile und zugleich flexible Architektur zu schaffen. In der Welt der Softwareentwicklung dreht sich alles rasend schnell: Anforderungen ändern sich, neue Technologien tauchen auf, und was gestern noch als gesetzt galt, ist heute schon ein Hindernis. Wie gelingt es, eine Architektur zu entwerfen, die als stabiles Fundament dient, ohne zum starren Korsett zu werden? Genau dieser Herausforderung widmet sich Richard Seidl in dieser Episode seines Podcasts Software Testing & Qualität. Zu Gast ist der Softwarearchitekt Ralf Enderle, der einen pragmatischen und zugleich wirkungsvollen Ansatz vorstellt. Gemeinsam erörtern sie, wie man Architektur-Entscheidungen klug kategorisiert, um Stabilität dort zu gewährleisten, wo sie nötig ist, und Evolution dort zu ermöglichen, wo sie nützt. Diese Folge ist ein unverzichtbarer Leitfaden für Architekt:innen, Entwickler:innen und Tester:innen, die den Spagat zwischen Planungssicherheit und agiler Anpassungsfähigkeit meistern wollen.

Das Wichtigste auf einen Blick

• Architektur in zwei Geschwindigkeiten: Der Schlüssel liegt darin, zwischen fundamentalen, schwer umkehrbaren Entscheidungen (Typ 1) und flexiblen, leicht änderbaren Entscheidungen (Typ 2) zu unterscheiden. Nicht jede Entscheidung muss für die Ewigkeit getroffen werden.
• Fundamentale Entscheidungen verteidigen: Typ-1-Entscheidungen, wie die Wahl zwischen einem Monolithen und einer Microservice-Architektur, bilden das Rückgrat des Systems. Sie erfordern sorgfältige Überlegung und müssen konsequent verteidigt werden.
• Evolution bei flexiblen Entscheidungen zulassen: Typ-2-Entscheidungen, etwa die Wahl eines Logging-Frameworks, sollten bewusst flexibel gehalten werden. Wenn das Team feststellt, dass eine andere Lösung besser passt, sollte eine Änderung unkompliziert möglich sein.
• Die sich selbst verteidigende Architektur: Statt auf passive Dokumente in einem Wiki zu vertrauen, sollte eine Architektur lebendig sein. Durch automatisierte Prüfungen wie Fitness Functions kann sie sich selbst gegen unerwünschte Abweichungen wehren und das Team alarmieren.
• Kontext durch KI: KI kann über einfache statische Code-Analysen hinausgehen. Sie kann den Kontext einer Architekturregel verstehen und beispielsweise erkennen, ob in einem Fehlerfall sensible Daten wie Kreditkartennummern geloggt werden - ein Mehrwert, den herkömmliche Tools kaum bieten.
• Teams befähigen, Gremien entlasten: Übergreifende Architektur-Boards sollten sich ausschließlich auf Typ-1-Entscheidungen konzentrieren. Alle anderen Entscheidungen gehören ins Entwicklungsteam, das die Realität der Software am besten kennt.

Das Kernproblem: Starre Pläne in einer agilen Welt

Richard eröffnet das Gespräch mit einer Beobachtung, die viele aus der Praxis kennen: Eine Architekturdokumentation ist oft schon in dem Moment veraltet, in dem sie fertiggestellt wird. Ralf Enderle bestätigt diesen Eindruck und erklärt, warum das besonders in agilen Umfeldern ein Problem darstellt. Während im klassischen Wasserfallmodell die Anforderungen über lange Zeit stabil bleiben, ist die Agilität darauf ausgelegt, auf Veränderungen zu reagieren, um stets den größtmöglichen Nutzen zu stiften. Eine Architektur, die über Monate im Elfenbeinturm entworfen wird, läuft Gefahr, von der Realität der Softwareentwicklung überholt zu werden. Die Kunst besteht also darin, einen Weg zu finden, der sowohl die notwendige strukturelle Führung bietet als auch die Freiheit lässt, auf neue Erkenntnisse und Anforderungen zu reagieren.

Typ 1 vs. Typ 2: Die Kunst der richtigen Entscheidung

Als zentrales Konzept stellt Ralf die Unterscheidung von Entscheidungen nach dem Vorbild von Jeff Bezos vor: Typ-1- und Typ-2-Entscheidungen. Er vergleicht sie mit Türen: Eine Typ-1-Entscheidung ist wie eine Tür, die hinter einem zufällt und sich nicht mehr öffnen lässt. Einmal getroffen, ist der Weg zurück extrem aufwendig oder gar unmöglich. Ein klassisches Beispiel hierfür ist die grundlegende Systemstruktur: der Wechsel von einem Monolithen zu Microservices (oder umgekehrt) ist in der Theorie einfach, in der Praxis jedoch ein immenses Unterfangen. Solche Entscheidungen erfordern tiefgehende Analyse und eine breite Zustimmung, da sie die DNA des Systems definieren.

Typ-2-Entscheidungen hingegen sind wie eine Schwingtür - man kann jederzeit problemlos zurückgehen. Die Wahl eines bestimmten Logging-Frameworks oder einer Testbibliothek fällt in diese Kategorie. Zwar ist eine Entscheidung notwendig, um voranzukommen, doch wenn sich herausstellt, dass sie nicht optimal war, lässt sie sich mit vertretbarem Aufwand korrigieren. Ralf betont, wie wichtig es ist, diesen Unterschied zu erkennen: Während man für Typ-1-Entscheidungen kämpfen muss, sollte man bei Typ-2-Entscheidungen die Evolution zulassen. Ein Team, das nach einigen Wochen merkt, dass eine andere Lösung besser passt, sollte die Freiheit haben, diese Anpassung vorzunehmen, ohne gegen starre Vorgaben ankämpfen zu müssen.

Von passiver Doku zu lebendiger Architektur

Ein wiederkehrendes Problem ist, dass Architekturdokumente - wie ADRs (Architecture Decision Records) - in einem Wiki verstauben und von niemandem gelesen werden. Ralf plädiert für einen radikal anderen Ansatz: Die Architektur muss lernen, sich selbst zu verteidigen. Anstatt ein passives Dokument zu sein, sollte sie aktiv in den Entwicklungsprozess eingreifen. Hier kommen Konzepte wie die von Neal Ford populär gemachten Fitness Functions ins Spiel. Dabei handelt es sich um automatisierte Tests, die überprüfen, ob die Architekturprinzipien eingehalten werden. Beispielsweise lässt sich die Performance als Qualitätsmerkmal durch KPIs definieren und in der CI/CD-Pipeline kontinuierlich testen. Schlägt ein solcher Test fehl, signalisiert das System sofort: Achtung, hier verletzt jemand eine wichtige architektonische Vorgabe. So wird die Architektur zu einem aktiven Wächter der Systemqualität, anstatt nur ein theoretisches Konstrukt zu sein.

Die Rolle des Teams und der Einsatz von KI

Wer trifft eigentlich diese Entscheidungen? Richard spricht das Problem des Architektur-Elfenbeinturms an, in dem Gremien Entscheidungen fällen, die an der Realität der Teams vorbeigehen. Ralfs Modell bietet hier eine klare Lösung: Das übergreifende Board kümmert sich ausschließlich um die fundamentalen Typ-1-Entscheidungen. Alle Typ-2-Entscheidungen sollten im Team getroffen werden, da es am nächsten an der Implementierung und den täglichen Herausforderungen dran ist. Dies befähigt die Teams und verhindert, dass Runden mit hoher Management-Beteiligung über Details wie die Wahl eines Frameworks diskutieren.

Zusätzlich eröffnet KI neue Möglichkeiten, um die Einhaltung von Architekturvorgaben zu überwachen. Ralf beschreibt ein eindrückliches Beispiel: Eine Regel könnte besagen, dass in jedem `catch`-Block zur Fehlerbehandlung ein Log-Eintrag erfolgen muss. Ein einfacher Test könnte dies per regulärem Ausdruck prüfen. Eine KI kann jedoch viel weiter gehen: Sie versteht den Kontext. Wenn in einem Modul zur Kreditkartenabwicklung ein Fehler auftritt, könnte die KI erkennen, dass das Logging der vollständigen Kreditkartennummer eine schlechte Idee ist - selbst wenn die formale Regel logge den Fehler erfüllt wäre. So wird die KI zu einem intelligenten Assistenten, der nicht nur Regeln prüft, sondern auch deren Intention versteht.

Praktische Schritte für eine evolutionsfähige Architektur

Wie kannst du diese Konzepte nun in deinem Projektalltag umsetzen? Ralf Enderle liefert eine klare Anleitung, um deine Architektur flexibler und robuster zu gestalten:

1. Klassifiziere deine Entscheidungen: Führe bei jeder wichtigen architektonischen Entscheidung eine bewusste Diskussion: Handelt es sich um eine schwer umkehrbare Typ-1-Entscheidung oder eine flexible Typ-2-Entscheidung? Nutze die Einweg-Tür-Metapher als Leitfaden.
2. Dokumentiere gezielt und mit Begründung: Konzentriere deine Dokumentationsaufwände auf die Typ-1-Entscheidungen. Erkläre nicht nur, *was* entschieden wurde, sondern vor allem, *warum*. Diese Begründung ist entscheidend, um die Regel auch in Zukunft verteidigen zu können. Halte die Dokumentation für Typ-2-Entscheidungen schlank.
3. Automatisiere die Überprüfung: Mache deine Architekturprinzipien messbar. Definiere KPIs und implementiere Fitness Functions, die automatisch in deiner CI/CD-Pipeline laufen. So erhältst du sofortiges Feedback, wenn eine Regel verletzt wird.
4. Gib dem Team die Verantwortung: Überlasse Typ-2-Entscheidungen vollständig dem Entwicklungsteam. Schaffe eine Kultur, in der es in Ordnung ist, solche Entscheidungen basierend auf neuen Erkenntnissen - zum Beispiel aus einer Retrospektive - zu revidieren.
5. Erlaube die Evolution: Verstehe, dass eine gute Architektur nicht in Stein gemeißelt ist. Sie wächst und passt sich mit dem System an. Indem du bewusst Raum für Änderungen bei Typ-2-Entscheidungen lässt, verhinderst du Stagnation und förderst eine kontinuierliche Verbesserung.