Die meisten Architektur-Reviews sind Theater. Ein Senior-Consultant fliegt ein, stellt zwei Tage lang höfliche Fragen, produziert ein 60-seitiges Foliendeck voller generischer Empfehlungen, präsentiert es dem Leadership-Team und verschwindet wieder. Das Team nickt brav. Zwei Monate später ist das Deck vergessen und nichts hat sich geändert.
Das liegt nicht daran, dass der Consultant schlecht oder das Team desinteressiert war. Es liegt daran, dass das Format falsch ist. Architektur-Reviews scheitern auf vorhersehbare Weise, und sie scheitern, weil sie so konzipiert sind, dass sich der Auftraggeber gut fühlt, nicht damit das System besser wird.
Dieser Essay handelt davon, wie ein wirklich nützliches Architektur-Review aussieht. Die Zehn-Tage-Struktur, auf die ich mich nach vielen solcher Einsätze festgelegt habe, die Artefakte, die den Meetingraum überleben, und die Gespräche, die den Unterschied ausmachen zwischen einem Deck, das abgeheftet wird, und einer Roadmap, die tatsächlich umgesetzt wird.
Wenn Sie ein Review beauftragen, ist das die Messlatte, die Sie fordern sollten. Wenn Sie eines durchführen, ist das die Messlatte, an der ich Sie messen würde.
Die Prämisse: Fakten zuerst, Urteile zuletzt, Wirkung immer
Drei Prinzipien prägen alles andere.
Fakten zuerst. Die erste Hälfte eines nützlichen Reviews ist Informationsbeschaffung. Code lesen. Incidents lesen. Commit-Historie lesen. Deployments beobachten. Mit Engineers darüber sprechen, was wehtut. Keine Empfehlungen aussprechen. Nichts als “Best Practices” framen. Einfach den tatsächlichen Zustand des Systems in ausreichender Tiefe erfassen, damit die Empfehlungen, wenn sie kommen, in etwas Konkretem verankert sind.
Urteile zuletzt. Empfehlungen sind im Abstrakten leicht zu formulieren und fast immer falsch. “Sie sollten CQRS einführen” ist eine generische Empfehlung. “Der Order-Placement-Flow hat eine Race-Condition, die unter Kampagnen-Last feuert, und CQRS würde sie nicht beheben. Was sie beheben würde, ist eine einzige transaktionale Grenze, hier, und wir schätzen 8 Engineer-Tage” ist eine nützliche Empfehlung. Der Unterschied liegt in der Arbeit zwischen Fakten und Urteilen.
Wirkung immer. Jede Empfehlung trägt Kosten des Tuns und Kosten des Nicht-Tuns, in konkreten Zahlen (Engineer-Wochen, Dollar pro Quartal an Incident-Kosten, Anzahl kundenseitig sichtbarer Fehler pro Monat). Ohne diese Zahlen ist die Empfehlung nicht finanzierbar, und eine nicht finanzierbare Empfehlung ist dasselbe wie keine Empfehlung.
Ein Review, das diesen drei Prinzipien folgt, produziert ein Artefakt, das den Meetingraum überlebt, weil die Empfänger damit handeln können. Ein Review, das das nicht tut, produziert ein Deck.
Der Zehn-Tage-Plan
Zwei Wochen reichen aus, um das gut zu machen. Sie reichen aber auch aus, damit das Team anfängt, den Einsatz zu fürchten, wenn er länger dauert. Zehn Arbeitstage, strukturiert.
Tag 1: Kickoff
Ein halber Tag mit der Engineering-Leitung und dem Executive Sponsor. Drei Dinge müssen festgezurrt werden:
Scope. Welches System, welche Sorgen, was ist ausgeschlossen. “Wir wollen ein Review der API und der Datenschicht; nicht des Frontends, nicht der Mobile Apps.” Konkrete Ausschlüsse sind genauso wichtig wie Einschlüsse.
Zielgruppe. Wer liest das finale Dokument. Der CTO ist eine andere Zielgruppe als der Vorstand. Das Format muss dazu passen. Wenn das Review für einen Vorstand ist, muss die Executive Summary in einem Absatz landen; ist es für das Engineering-Team, kann die Tiefe weiter gehen.
Die treibende Sorge. Welche Sorge hat den Auftrag ausgelöst? “Wir stehen vor einer Skalierung um den Faktor 10 und wollen wissen, was bricht.” “Wir erwägen ein Rewrite und wollen eine zweite Meinung.” “Wir hatten drei Incidents in drei Monaten und wissen nicht, ob sie zusammenhängen.” Die ehrliche Antwort auf diese Frage prägt jedes folgende Gespräch. Lautet die Antwort “der Vorstand hat es verlangt und wir wissen eigentlich gar nicht, was wir wollen”, ist das in Ordnung, aber sagen Sie es so.
Die andere Hälfte von Tag eins ist Zugriff. Lese-Zugriff auf das Repository, den Issue-Tracker, Incidents und Postmortems, Dashboards, die Cloud-Accounts. Dauert der Zugriff länger als einen Tag, startet das Review zu spät, was alles Folgende staucht.
Tage 2-3: Discovery
Das sind Lesetage. Ziel ist es, ein mentales Modell des Systems aufzubauen, bevor man mit irgendjemandem tiefer spricht.
Das Repository. Die Codebasis durchgehen. Nicht jede Datei. Die Dateien mit hohem Traffic: die Controller, die Einstiegspunkte, die zentralen Entities, die Message-Handler. Blick auf Dateigrößen (jede Datei über 800 Zeilen ist ein Warnsignal), auf Verzeichnisstrukturen (jedes Verzeichnis mit 50 und mehr Dateien ist ein Warnsignal), auf die Dependency-Oberfläche (composer.lock, die Anzahl der Pakete, das Alter der Major-Versionen).
Die Git-Historie. Die letzten zwölf Monate an Commits. Was hat sich am meisten verändert? Wo liegen die Hot Files (jedes Projekt hat 5 bis 10 Dateien, die in 80 Prozent der Pull Requests angefasst werden)? Wer committet wohin (dominiert eine einzelne Person eine Region, deutet das meist entweder auf Expertise oder auf Risikokonzentration hin, oft auf beides).
Der Issue-Tracker. Offene Bugs, jüngste Incidents, die ältesten Einträge im Backlog. Das Verhältnis von Bug-Tickets zu Feature-Tickets ist ein nützliches Signal. Das Alter der ältesten Tickets ist ein nützliches Signal. Die Muster in Postmortems sind sehr nützliche Signale.
Die Dashboards. Latency, Fehlerraten, Throughput, Queue-Tiefen, Datenbanklast. Was ist normal? Was spitzt sich? Worauf schaut das Team, und worauf schaut das Team nicht?
Am Ende von Tag 3 sollten Sie eine einseitige Zusammenfassung der Systemform in Ihren eigenen Notizen haben. Noch nicht zum Teilen. Sie dient als Rückgrat der folgenden Gespräche.
Tage 4-6: Deep-Dive-Interviews
Drei Tage Gespräche. Drei bis fünf Engineers pro Tag, jeweils 60 bis 90 Minuten. Die Liste kommt vom Leadership-Team, mit einer Regel: Mindestens ein unzufriedener Engineer muss dabei sein. Reviews, die nur mit den zufriedenen Engineers sprechen, produzieren Reviews, die nur die komfortablen Teile des Systems dokumentieren.
Die Fragen sind keine Architektur-Fragen. Es sind Arbeitsfragen.
- Was haben Sie in den letzten zwei Wochen ausgeliefert? Führen Sie mich da durch.
- Was wollten Sie ausliefern und es war schwerer als erwartet? Warum?
- Welchen Teil des Systems meiden Sie, wenn Sie können, wenn Änderungen anstehen?
- Wenn ich Ihnen eine Woche ohne Feature-Arbeit gäbe, was würden Sie zuerst reparieren?
- Was war das Letzte, das Sie um 3 Uhr morgens geweckt hat? Wie sah das Postmortem aus?
- Wenn Sie einem neu ins Team kommenden Engineer eine Sache über dieses System erklären müssten, welche wäre das?
- Wenn Sie den nächsten größeren Incident vorhersagen müssten, welcher wäre das?
Diese Fragen bringen die gelebte Erfahrung mit dem System an die Oberfläche, die fast immer von der Version abweicht, die der Leitung erzählt wird. Die Muster wiederholen sich über die Engineers hinweg. Ab dem dritten Interview können Sie meist die Hälfte dessen vorhersagen, was der nächste Engineer sagen wird. Nach dem achten oder neunten haben Sie ein verlässliches Bild davon, wo das System tatsächlich wehtut.
Tag 7: Analyse
Ein fokussierter Tag der Synthese. Keine Meetings. Die Artefakte bauen, auf denen die zweite Hälfte des Einsatzes ruht.
Das Systemdiagramm. Nicht das aus dem Wiki. Das, das zu dem passt, was die Engineers tatsächlich beschrieben haben. Das ist meist der Moment, in dem ein stiller Makel laut wird: Das Wiki-Diagramm zeigt sechs saubere Services; das tatsächliche System hat drei Services, die sich über eine geteilte Datenbank und ein vergessenes Middleware-Stück, auf das sich alle verlassen, ineinander verstricken.
Das Risikoregister. Aus Incidents, Interviews und Code-Beobachtungen gezogen. Jeder Eintrag: was das Risiko ist, wie es sich manifestiert, wie wahrscheinlich es in den nächsten sechs Monaten feuert, was es auslöst, welchen Blast Radius es hat. Verwenden Sie dieselbe Severity-Skala wie für produktive Incidents. Erfinden Sie keine eigene Skala.
Das Decision Log. Die wesentlichen architektonischen Entscheidungen, die das System widerspiegelt. Einige davon sind dokumentiert (als Architecture Decision Records, wenn Sie Glück haben). Die meisten nicht. Rekonstruieren Sie sie aus Interviews und Code-Archäologie. Kennzeichnen Sie jede als “weiterhin tragend”, “tragend, sollte aber überdacht werden” oder “Entscheidung inzwischen revidiert, aber Artefakte bleiben”. Diese Liste ist für das Leadership-Team oft die überraschendste.
Die Hotspot-Karte. Die 5 bis 10 Stellen im Code, an denen die meisten jüngsten Änderungen konzentriert sind und das meiste zukünftige Risiko lebt. Aus Git ziehen, aus Incident-Orten, aus Interview-Erwähnungen. Adam Tornhills Arbeit Code as a Crime Scene ist die kanonische Referenz dafür, die VCS-Historie zu nutzen, um diese Hotspots zu finden.
Am Ende von Tag 7 liegt das Rohmaterial vor. Die nächsten drei Tage verwandeln es in das Artefakt.
Tage 8-9: Synthese und Priorisierung
Zwei Tage schreiben. Das Format, das bei mir am besten funktioniert hat:
Abschnitt 1: Executive Summary. Eine Seite. Drei bis fünf Bullets oben mit den wichtigsten Befunden. Ein Absatz zu jedem. Der CTO und der CFO lesen das und sonst nichts; entsprechend gestalten.
Abschnitt 2: Systemüberblick. Was das System tatsächlich ist. Das ehrliche Diagramm. Die Bounded Context Map (oder deren Abwesenheit). Das Datenmodell auf der Ebene “was sind die zentralen Entities und wie hängen sie zusammen”. Zwei bis vier Seiten.
Abschnitt 3: Risikoregister. Die Top 10 bis 15 Risiken mit Severity, Blast Radius, geschätzten Kosten der Behebung und geschätzten Kosten des Nicht-Behebens. Dieser Abschnitt wird zum Planungsinstrument für das nächste Quartal.
Abschnitt 4: Empfehlungen. Konkret, durchkostet, in Reihenfolge gebracht. Nicht “Microservices in Betracht ziehen”. Sondern: “Extrahieren Sie die Billing-Capability in einen eigenen Bounded Context hinter einer Routing-Naht, mit dem Messaging-Vertrag, der im Anhang spezifiziert ist. Geschätzt 6 bis 8 Engineer-Wochen. Reduziert den Blast Radius der Race-Condition im Order-Placement. Sollte vor der Frühjahrskampagnen-Last erledigt sein.”
Abschnitt 5: Ein 90-Tage-Plan. Drei bis fünf konkrete Schritte, geordnet, mit erwarteten Ergebnissen. Der erste Schritt sollte innerhalb der nächsten zwei Wochen machbar sein; das gibt dem Team einen frühen Erfolg und beweist, dass das Review nicht bloß ein Deck war.
Abschnitt 6: Außerhalb des Scopes, aber wichtig. Dinge, die während des Reviews aufkamen, aber außerhalb des vereinbarten Scopes lagen und die das Leadership-Team dennoch kennen sollte. Manchmal sind diese größer als die Befunde im Scope.
Tag 10: Validierung und Übergabe
Ein halber Tag mit dem Engineering-Team. Führen Sie es durch das Dokument. Hören Sie auf “das stimmt so nicht ganz” und “das haben Sie übersehen” und “das haben wir vor zwei Jahren versucht und so ist es ausgegangen”. Aktualisieren Sie das Dokument live. Die Kalibrierung durch die Engineers ist der Validierungsschritt.
Die andere Hälfte des Tages mit dem Executive Sponsor. Führen Sie ihn durch die Executive Summary und den 90-Tage-Plan. Holen Sie ein explizites Ja oder Nein zu den ersten drei Schritten. Ohne die explizite Zusage wandert das Dokument in dieselbe Schublade wie jede andere Consulting-Lieferung.
Das ist der Einsatz. Zwei Wochen rein, zwei Wochen raus, mit einem durchkosteten und zugesagten Plan als Ergebnis.
Was in welcher Reihenfolge ins Dokument gehört
Die Reihenfolge des Dokuments ist genauso wichtig wie der Inhalt. Die Reihenfolge, die ich verwende, mit der Begründung:
- Executive Summary. An erster Stelle, weil die meisten Leser hier aufhören. Lesen sie nur diesen Teil, sollten sie trotzdem die Kernbotschaft und die empfohlenen Maßnahmen mitnehmen.
- Was wir untersucht haben und was nicht. An zweiter Stelle, weil es ehrliche Erwartungen setzt. Ein Review, das die API untersucht hat, aber nicht die Datenschicht, sollte das vorn sagen, damit der Leser keine Schlüsse zur Datenschicht unterstellt.
- Systemüberblick. An dritter Stelle, weil er das geteilte Verständnis bildet, auf dem der Rest des Dokuments ruht.
- Risikoregister. An vierter Stelle, weil das Leadership-Team genau dagegen Budget freigeben wird.
- Empfehlungen. An fünfter Stelle, weil sie nur im Licht der Risiken Sinn ergeben.
- 90-Tage-Plan. An sechster Stelle, weil er die operative Übergabe ist.
- Hinweise außerhalb des Scopes. An siebter Stelle, weil sie dort stehen müssen, aber nicht von den Schlussfolgerungen im Scope ablenken dürfen.
- Anhänge. An achter Stelle: die Daten hinter den Diagrammen, die vollständige Interviewliste, die Incident-Timeline, die Langfassungen der Risiken.
Ein Dokument in dieser Reihenfolge ist für die Executive-Seite in 15 Minuten lesbar und für das Engineering-Team in 90 Minuten. Ein Dokument, das die Empfehlungen nach hinten vergräbt, respektiert die Zeit seiner Leser nicht.
Wie Empfehlungen aussehen sollten, und wie nicht
Ich habe genug Architektur-Review-Decks gesehen, um starke Meinungen darüber zu haben, was Empfehlungen umsetzbar macht.
Gute Empfehlungen sind konkret. “Fügen Sie einen Index auf orders.customer_id hinzu, um das N+1-Problem im Customer-History-Endpoint zu beheben” ist konkret. “Datenbank-Performance verbessern” ist es nicht.
Gute Empfehlungen sind in Reihenfolge gebracht. Der 90-Tage-Plan sollte klarmachen, was zuerst zu tun ist, was wovon abhängt und was warten kann. Eine flache Liste von 30 Punkten ist Lähmung.
Gute Empfehlungen sind durchkostet. Engineer-Wochen. Dollar. Kundenwirkung. Ohne Zahlen kann das Leadership-Team sie nicht finanzieren, und unfinanzierte Empfehlungen sind dasselbe wie keine.
Gute Empfehlungen sind umkehrbar. Wo möglich, empfehlen Sie Schritte, die das Team rückgängig machen kann, wenn sich etwas herausstellt. “Extrahieren Sie die Billing-Capability hinter einem Feature Flag und rollen Sie sie schrittweise aus” ist umkehrbar. “Schreiben Sie den Checkout in Go neu” ist es nicht.
Schlechte Empfehlungen kommen aus Playbooks, nicht aus dem System. Hätten die Empfehlungen ohne die Discovery geschrieben werden können, hat die Discovery sie nicht verändert, was bedeutet, dass sie nicht deren Input war. Das ist der häufigste einzelne Fehlermodus.
Schlechte Empfehlungen werden als “Best Practices” geframt. Best Practice bedeutet ohne Kontext nichts. Die richtige Architektur für ein 12-Engineer-Team ist nicht die richtige Architektur für ein 4-Engineer-Team. Die richtige Architektur für eine API mit einer Million Requests pro Tag ist nicht die richtige Architektur für eine mit 10.000 Requests pro Tag. Generische Best Practices sind, wie Reviews aufhören, nützlich zu sein.
Schlechte Empfehlungen werden gebündelt. “Führen Sie CQRS, Event Sourcing, Microservices und ein Service Mesh ein” sind sechs zusammengetackerte Empfehlungen, von denen keine für sich allein bewertbar ist. Jede muss für sich stehen oder fallen.
Wogegen zu widersprechen ist, auch wenn der Kunde danach fragt
Drei Muster, in denen der Kunde etwas Bestimmtes will und die richtige Antwort ein Widerspruch ist.
“Sagen Sie uns, ob wir neu schreiben sollen.” Diese Frage löst viele Reviews aus. Die ehrliche Antwort ist fast immer “nein, nicht neu schreiben, hier ist der Migrationspfad, der Ihnen den größten Teil des Werts bei einem Bruchteil des Risikos bringt”. Kunden wollen diese Antwort manchmal nicht; sie haben sich schon für das Rewrite entschieden und suchen Bestätigung. Die Aufgabe des Reviews ist es, ihnen die ehrliche Antwort zu geben, mit den Daten dahinter, und sie selbst entscheiden zu lassen. Ein Review, das ein Rewrite abnickt, zu dem sich der Kunde bereits verpflichtet hat, ist kein Review.
“Empfehlen Sie die Technologie X, die wir in Betracht ziehen.” Dieselbe Dynamik. Die fragliche Technologie mag passend sein oder auch nicht. Die Aufgabe des Reviews ist, sie gegen das tatsächliche System zu bewerten, nicht die vorherige Entscheidung zu bestätigen. Lautet die Empfehlung “X nicht einführen, hier ist warum, hier ist, was stattdessen zu tun ist”, dann gehört das ins Dokument.
“Machen Sie das Deck kürzer, mit weniger Warnungen.” Der Executive Sponsor wünscht sich manchmal ein positiveres Dokument, weil es vom Vorstand, von Investoren oder von einem Kunden gelesen wird. Richtig ist: Warnungen in der Engineering-Version behalten und eine separate Executive-Version erstellen, die kürzer ist, aber nicht lügt. Ein Review, das seine Befunde weichspült, um dem Publikum zu gefallen, ist schlimmer als kein Review.
Häufige Fehlermodi
Reviews, die keine Veränderung erzeugen, scheitern meist auf dieselbe Weise.
Das Review macht nie Kontakt mit den Engineers. Der Consultant spricht nur mit der Leitung. Das Review spiegelt die Version des Systems, an die die Leitung glaubt, nicht die, in der die Engineers arbeiten. Immer Engineers interviewen, immer die Unzufriedenen einschließen.
Das Review dokumentiert Probleme, aber nicht deren Folgen. “Die Order-Verarbeitung hat duplizierte Logik an drei Stellen” ist ein Fakt, kein Problem. Warum ist das wichtig? Was kostet es? Welcher Kunde ist betroffen? Ohne die Konsequenz ist die Empfehlung nicht finanzierbar.
Das Review empfiehlt Dinge, die Freigaben erfordern, die der Kunde nicht hat. “Stellen Sie ein 30-köpfiges Platform-Team ein” ist keine Empfehlung, auf die ein CTO allein reagieren kann. Empfehlungen sollten im Mandat der Empfänger liegen, oder sie müssen als eskalationsbedürftig markiert sein.
Das Review ist zu lang. Ein 200-seitiges Dokument wird nicht gelesen. Zwingen Sie sich unter 40 Seiten, die meiste Tiefe in die Anhänge. Die 40-seitige Version ist die, die Entscheidungen produziert.
Das Review bekommt kein Follow-up. Ein Review ohne 90-Tage-Check-in ist ein Review, das abgeheftet wird. Bauen Sie das Follow-up in den Einsatz ein.
Womit Kunden rechnen sollten
Ein zweiwöchiges Architektur-Review für ein System relevanter Größe ist ein ernsthafter Einsatz. Rechnen Sie auf Consulting-Seite mit dem Äquivalent von zwei Senior-Engineer-Wochen, plus die Zeit der interviewten Engineers und des Executive Sponsors. Gesamtbelastung: grob drei bis vier Engineer-Wochen organisatorischer Zeit, plus das Consulting-Honorar.
Das ist nicht billig. Es ist auch nicht teuer gemessen an den Kosten der falschen architektonischen Entscheidung, die sich oft in Quartalen gebremster Feature-Velocity oder in Millionen an gescheiterten Rewrites messen lässt.
Das Signal, dass das Review seinen Preis wert war, ist in jedem Fall dasselbe: Ist das System in messbarer Weise besser geworden, in den sechs Monaten danach? Ein Review, das drei konkrete Schritte angestoßen hat, die Incident-Raten gesenkt, die Deployment-Frequenz erhöht oder ein Feature freigeschaltet haben, das das Team vorher nicht ausliefern konnte, hat sich vielfach bezahlt gemacht. (DORA hat über Jahre hinweg gezeigt, dass Deployment-Frequenz, Lead Time, Change Failure Rate und Time to Restore die vier Metriken sind, die die Lieferperformance nachzeichnen; bewegt ein Review mindestens eine dieser Metriken in den folgenden zwei Quartalen nicht, hat es vermutlich nicht getroffen.) Ein Review, das ein Deck produziert hat, hat sich nicht bezahlt gemacht.
Wann Sie kein Review brauchen
Nicht jedes System braucht jedes Quartal ein Review. Lassen Sie es, wenn:
- Das System klein ist (unter 30.000 Zeilen, unter 4 Engineers) und das Team sich einig ist, was wehtut. Sie brauchen keinen Außenstehenden, der Ihnen sagt, was Sie ohnehin wissen. Stecken Sie das Geld in die Behebung.
- Sie in den letzten sechs Monaten eines beauftragt haben und die Empfehlungen noch in Umsetzung sind. Ein zweites Review während der Umsetzung bringt Rauschen und demoralisiert das Team. Warten Sie, bis der erste Schritteblock erledigt ist und sich das Bild verändert hat.
- Das Leadership-Team die Befunde nicht umsetzen wird. Ein Review, das in eine Kultur geliefert wird, die Engineering-Arbeit nicht finanziert, erzeugt null Veränderung. Kümmern Sie sich zuerst um die Finanzierungskultur; das Review kommt später.
Für alle anderen ist ein fokussiertes zweiwöchiges Review alle 12 bis 18 Monate einer der hebelreichsten Einsätze einer externen Perspektive, die eine Engineering-Organisation vornehmen kann.
Wenn Sie ein System haben, zu dem Sie einen klaren, ehrlichen, durchkosteten Blick wünschen, startet mein Monolith-Modernisierungseinsatz mit genau diesem zweiwöchigen Review. Zwei Wochen Einsatz, ein 35-seitiges Dokument und ein 90-Tage-Plan, dessen erster Schritt noch vor Ende des Einsatzes ausgeliefert wird.
Referenzen
- Documenting Architecture Decisions von Michael Nygard: der Blogpost aus 2011, der ADRs als leichtgewichtiges Format für Kontext, Entscheidung und Konsequenzen eingeführt hat.
- Architecture Decision Record Templates und Beispiele: Joel Parker Hendersons kuratierte Sammlung von ADR-Templates, darunter Nygard, MADR und die Tyree-Varianten.
- Code as a Crime Scene von Adam Tornhill: der ursprüngliche Essay zur Nutzung von VCS-Historie und logischer Kopplung, um Hotspots zu finden, erweitert im gleichnamigen Buch.
- Your Code as a Crime Scene (Pragmatic Bookshelf): Tornhills Buch zur Anwendung verhaltensbasierter Code-Analyse auf die Priorisierung technischer Schulden.
- DORA (DevOps Research and Assessment): das langjährige Forschungsprogramm hinter den vier zentralen Lieferkennzahlen, die ein gutes Review in den folgenden zwei Quartalen bewegen sollte.
