Architecture Change Requests: Pull Requests für Ihr C4-Modell
Letzten Monat hat ein Ingenieur in einem Team, das ich berate, einen zentralen Service in ihrem Architekturdiagramm umbenannt. Keine Diskussion. Keine Prüfung. Die Änderung war sofort live, und drei Teams verbrachten das nächste Standup damit, sich zu fragen, ob der eigentliche Service umbenannt wurde oder nur das Diagramm. War er nicht. Jemand fand das Label einfach unklar und hatte es "korrigiert".
Dieser Vorfall hat etwas kristallisiert, worüber wir schon eine Weile nachgedacht hatten. Code hat Pull Requests. Infrastruktur hat Plan/Apply. Datenbankschemas haben Migrationen. Aber Architekturdiagramme? Jeder mit Bearbeitungszugriff kann alles jederzeit ändern, und der Rest des Teams erfährt es... irgendwann.
Heute ändern wir das. Architecture Change Requests bringen den Pull-Request-Workflow in Ihr C4-Modell.
So funktioniert es
Das Konzept ist bewusst vertraut. Wenn Sie jemals einen Pull Request auf GitHub erstellt haben, wissen Sie bereits, wie das funktioniert.
Sie beginnen mit dem Erstellen einer Change Request. Geben Sie ihr einen Titel, beschreiben Sie, was Sie vorschlagen und warum. Dann fügen Sie Ihre Änderungen hinzu: neue Systeme erstellen, bestehende Container aktualisieren, ungenutzte Komponenten löschen, Beziehungen ändern. Jede Änderung ist eine diskrete Operation: Erstellen, Aktualisieren oder Löschen eines bestimmten C4-Elements.
Die Change Request beginnt als Entwurf. Sie können weiter Änderungen hinzufügen und verfeinern, bis Sie bereit sind. Wenn der Vorschlag vollständig ist, öffnen Sie ihn zur Prüfung.
Ihre Teammitglieder sehen die offene Anfrage in der Change-Request-Liste des Projekts. Sie können jede vorgeschlagene Änderung prüfen, genau sehen, was erstellt, geändert oder entfernt wird. Sie hinterlassen Reviews: genehmigen, Änderungen anfordern oder kommentieren. Sobald die erforderliche Anzahl an Genehmigungen erreicht ist, kann die Anfrage zusammengeführt werden — alle Änderungen werden in einer einzigen atomaren Operation auf das Live-C4-Modell angewendet.
Visuelle Vorschau
Eine Sache, die wir nicht wollten, war eine Diff-Ansicht, die sich wie ein JSON-Blob liest. Architektur ist visuell, und die Prüfung von Architekturänderungen sollte es auch sein.
Jede Change Request enthält eine Live-Vorschau des Diagramms. Die Vorschau rendert das aktuelle C4-Modell mit allen vorgeschlagenen Änderungen überlagert. Neue Elemente erscheinen mit grüner Hervorhebung. Geänderte Elemente erhalten einen bernsteinfarbenen Ring. Gelöschte Elemente zeigen einen roten Indikator. Sie können durch die C4-Ebenen navigieren — System, Container, Komponente, Code — und die vollständige Auswirkung des Vorschlags auf jeder Tiefe sehen.
Es ist dasselbe interaktive React-Flow-Canvas, das Sie für das Live-Diagramm verwenden, mit demselben Drill-Down, Zoom und Schwenken. Der einzige Unterschied sind die Daten: Es ist eine berechnete Projektion dessen, wie die Architektur nach dem Zusammenführen aussehen wird.
Der Review-Prozess
Reviews folgen einem einfachen Modell. Ein Reviewer kann:
- Genehmigen — "Sieht gut aus, zusammenführen wenn bereit."
- Änderungen anfordern — "Ich habe Bedenken, lass uns das besprechen, bevor es rein kommt."
- Kommentieren — "Kein Einwand, aber hier ist etwas Kontext."
Jedes Review enthält ein Freitextfeld für detailliertes Feedback. Die Change Request verfolgt ihre Genehmigungsanzahl gegenüber dem erforderlichen Schwellenwert des Projekts. Standardmäßig ist eine Genehmigung erforderlich, aber Sie können dies pro Projekt konfigurieren — null Genehmigungen für kleine Teams, die ein schlankes Tracking wünschen, zwei oder drei für größere Organisationen, die eine formelle Freigabe benötigen.
Nur-Anfragen-Modus
Für Teams, die noch weiter gehen wollen, haben wir einen Nur-Anfragen-Modus in den Projekteinstellungen hinzugefügt. Wenn aktiviert, sind direkte Bearbeitungen am C4-Modell gesperrt. Der einzige Weg, die Architektur zu ändern, führt über eine Change Request.
Das bedeutet nicht, dass das Diagramm schreibgeschützt wird. Sie können weiterhin navigieren, erkunden, ADRs und Dokumentation mit Elementen verknüpfen, Kommentare hinzufügen. Sie können nur keine Elemente verschieben, umbenennen, erstellen oder löschen, ohne den Change-Request-Workflow zu durchlaufen.
Wir haben dies für Organisationen gebaut, in denen Architektur-Governance wichtig ist — regulierte Branchen, große Ingenieurteams, Plattformteams, die gemeinsame Infrastruktur verwalten. Die Architektur wird zu einem kontrollierten Artefakt, bei dem jede Änderung nachvollziehbar und geprüft ist.
Aktivitatsverfolgung
Jedes Lifecycle-Ereignis einer Change Request erscheint im Aktivitats-Tab des Projekts. Wenn eine Anfrage geöffnet, geschlossen, wieder geöffnet oder zusammengeführt wird, wird ein Historieneintrag mit Autor, Zeitstempel und Anfragetitel aufgezeichnet. Das gibt Ihnen eine Zeitleiste, wie sich die Architektur entwickelt hat — nicht nur, wie sie heute aussieht, sondern die Abfolge von Vorschlagen und Entscheidungen, die sie geformt haben.
Kombiniert mit ADRs und Dokumentationslinks erhalten Sie eine vollständige Erzählung: was sich geändert hat (die Change Request), warum es sich geändert hat (der ADR) und wie es in den breiteren Kontext passt (die Dokumentation).
Änderungen erstellen
Der Change Builder lässt Sie Vorschläge Element für Element aufbauen. Für jede Änderung geben Sie an:
- Operation: Erstellen, Aktualisieren oder Löschen
- Elementtyp: System, Container, Komponente, Code-Element, Beziehung oder Overlay
- Elementdaten: die vollständige Spezifikation des Elements — Name, Beschreibung, Technologie, Typ und alle Felder, die Sie beim direkten Erstellen ausfüllen würden
Für Aktualisierungen erfasst das System sowohl den aktuellen als auch den vorgeschlagenen Zustand, damit Reviewer genau sehen, was sich ändert. Für Löschungen werden die bestehenden Elementdaten in der Anfrage zur Referenz aufbewahrt.
Sie können Operationen frei mischen. Eine einzelne Change Request kann zwei neue Container erstellen, eine Beziehung aktualisieren und eine veraltete Komponente löschen. Beim Zusammenführen werden alle Änderungen gemeinsam angewendet.
Was das für Teams bedeutet
Architecture Change Requests sind nicht dazu da, Bürokratie hinzuzufügen. Sie sind dazu da, architektonische Weiterentwicklung bewusst zu gestalten.
In einer Codebasis ist der Pull Request nicht nur eine Schranke — er ist ein Kommunikationswerkzeug. Er sagt "hier ist, was ich vorschlage, hier ist warum, was denkt ihr?" Er schafft einen natürlichen Moment für Wissensaustausch, um Fehler früh zu erkennen, um ein gemeinsames Verständnis aufzubauen.
Architektur verdient die gleiche Behandlung. Wenn jemand vorschlägt, einen neuen Service hinzuzufügen, ist das ein Gespräch, das es wert ist, geführt zu werden, bevor er auf dem Diagramm erscheint. Wenn jemand die Komponentenhierarchie umstrukturieren mochte, sollte das Team das vollständige Bild sehen, bevor es zur neuen Realität wird.
Die Change Request ist dieses Gespräch, strukturiert und nachvollziehbar gemacht.
Erste Schritte
Architecture Change Requests sind ab sofort auf allen Team-Plänen verfügbar. Navigieren Sie zu einem beliebigen Projekt, und Sie finden den Bereich "Anfragen" in der Seitenleiste. Erstellen Sie Ihre erste Anfrage, fügen Sie einige Änderungen hinzu und öffnen Sie sie zur Prüfung.
Wenn Sie den Workflow durchsetzen möchten, aktivieren Sie den Nur-Anfragen-Modus in Ihren Projekteinstellungen. Konfigurieren Sie die erforderliche Genehmigungsanzahl entsprechend den Governance-Anforderungen Ihres Teams.
Ihre Architektur ist eine Teamentscheidung. Jetzt machen Ihre Werkzeuge das explizit.
Möchten Sie mehr über kollaborative Architektur erfahren? Lesen Sie über die Echtzeit-Zusammenarbeit an C4-Diagrammen, oder erfahren Sie, wie Architecture Decision Records Change Requests ergänzen, indem sie das "Warum" hinter jeder architektonischen Weiterentwicklung festhalten.