Architecture Drift ist die Lücke zwischen dem System, das Sie dokumentiert haben, und dem System, das Sie tatsächlich haben. Die üblichen Ratschläge dazu (die Docs neben den Code legen, sie im Pull Request mit reviewen) sind gut, und keiner davon sagt Ihnen, ob es funktioniert hat. Dieser Leitfaden behandelt, was Drift ist, wie man ihn erkennt und wie man die Lücke, die Sie ohnehin schon haben, in eine Zahl fasst.

Architecture Drift Detection: Code und Design im Einklang halten

Irgendwo in Ihrer Organisation gibt es ein Architekturdiagramm, das falsch ist. Vielleicht zeigt es einen Microservice, der vor sechs Monaten in einen anderen zusammengeführt wurde. Vielleicht listet es Redis als Caching-Schicht auf, obwohl das Team während eines Produktionsvorfalls auf Memcached umgestellt hat. Vielleicht beschreibt es eine saubere hexagonale Architektur in einem Service, der genug Abkürzungen und Workarounds angesammelt hat, um wie Spaghetti auszusehen.

Das ist Architecture Drift: die allmähliche, stille Divergenz zwischen der Dokumentation Ihres Systems und seiner tatsächlichen Funktionsweise. Im Gegensatz zu Bugs löst Drift keine Alerts aus. Im Gegensatz zu Performance-Regressionen erscheint er nicht im Monitoring. Er wartet still, bis jemand eine Entscheidung auf Basis veralteter Dokumentation trifft -- und diese Entscheidung sich als falsch erweist.

Architecture Drift ist universell. Jedes Team erlebt ihn. Die Frage ist nicht, ob Ihre Dokumentation abdriften wird, sondern wie schnell Sie es bemerken und was Sie dagegen tun.

An Ratschlägen zur zweiten Hälfte dieser Frage herrscht kein Mangel. Legen Sie die Docs neben den Code. Reviewen Sie sie im selben Pull Request. Machen Sie sie zum Teil der Definition of Done. Das sind gute Ratschläge, das meiste davon steht weiter unten auf dieser Seite, und sie teilen einen blinden Fleck: Sie sagen Ihnen, was zu tun ist, nicht, ob es funktioniert hat. Das, was in der gängigen Empfehlung einer Prüfung am nächsten kommt, ist ein Zeitstempel der letzten Änderung -- und der sagt Ihnen, wann jemand die Datei angefasst hat, nicht, ob die Datei stimmt.

Drift zu erkennen ist die Hälfte, die übersprungen wird. Dieser Leitfaden behandelt das Problem, die fünf Familien von Erkennungsmethoden und was jede davon sehen kann und was nicht. Zwei begleitende Artikel gehen jeweils bei einem Punkt in die Tiefe: wie ein Drift Score berechnet wird und was die Zahl bedeutet und die Praktiken, die ein Modell wahr halten, sobald Sie eines haben.

Was ist Architecture Drift?

Architecture Drift tritt auf, wenn die tatsächliche Implementierung eines Softwaresystems von seiner dokumentierten oder beabsichtigten Architektur abweicht. Perry und Wolf haben das Problem in Foundations for the Study of Software Architecture (ACM SIGSOFT Software Engineering Notes, 1992) benannt und dort erosion (Erosion), die aus der Verletzung der Architektur entsteht, von drift getrennt, der aus Unempfindlichkeit ihr gegenüber entsteht. Der alltägliche Sprachgebrauch hat sich seither verschoben: Die meisten Ingenieure sagen heute "Drift" für jede Lücke zwischen Dokumentation und Code, und in diesem Sinne verwendet ihn dieser Leitfaden. Die Unterscheidung lohnt sich trotzdem, und weiter unten gibt es einen Abschnitt dazu.

Drift manifestiert sich auf jeder Ebene der Architekturdokumentation:

Struktureller Drift

Die dokumentierte Struktur stimmt nicht mehr mit der Codebasis überein:

Ein Service, der als eigenständiger Container dokumentiert ist, wurde in einen Monolithen absorbiert
Eine Komponente wurde umbenannt, aber das Diagramm zeigt immer noch den alten Namen
Ein neuer Service wurde erstellt, aber nie zum Architekturmodell hinzugefügt
Eine Datenbank wurde von MySQL auf PostgreSQL migriert, aber das Container-Diagramm sagt immer noch MySQL

Verhaltensbezogener Drift

Das dokumentierte Verhalten stimmt nicht mehr mit der Realität überein:

Ein synchroner API-Aufruf wurde durch eine asynchrone Nachricht ersetzt, aber die Beziehung sagt immer noch "REST/HTTP"
Ein Datenfluss wurde so geändert, dass er über ein API Gateway läuft, aber das Diagramm zeigt direkte Service-zu-Service-Kommunikation
Ein Authentifizierungsschritt wurde hinzugefügt, der sich nicht im System-Context-Diagramm widerspiegelt

Abhängigkeits-Drift

Die dokumentierten Abhängigkeiten stimmen nicht mehr mit den tatsächlichen Integrationen überein:

Eine Drittanbieter-API wurde durch eine interne Lösung ersetzt
Eine neue externe Abhängigkeit wurde hinzugefügt (Zahlungsanbieter, Monitoring-Service), aber nicht dokumentiert
Eine Integration wurde außer Betrieb genommen, erscheint aber weiterhin im System-Context-Diagramm

Entscheidungs-Drift

Die dokumentierten architektonischen Entscheidungen werden nicht mehr befolgt:

Ein ADR sagt "PostgreSQL für alle persistente Datenhaltung verwenden", aber ein Team hat begonnen, MongoDB zu verwenden
Die Conformance Rules sagen "kein direkter Datenbankzugriff vom Frontend", aber jemand hat eine clientseitige Supabase-Integration hinzugefügt
Die Deployment-Architektur sagt "Single Region", aber Services wurden in mehreren Regionen deployed

Warum Architecture Drift entsteht

Die Ursachen von Drift zu verstehen ist essenziell, um ihm vorzubeugen. Drift geschieht normalerweise nicht böswillig oder gar fahrlässig -- er ist eine natürliche Konsequenz der Art, wie Software entwickelt wird.

Geschwindigkeit vor Dokumentation

Wenn ein Feature bis Freitag ausgeliefert werden muss, ist die Aktualisierung des Architekturdiagramms das Erste, was gestrichen wird. Die Code-Änderung ist das Ergebnis. Die Dokumentationsaktualisierung ist Overhead. Das ist kurzfristig rationales Verhalten und langfristig verheerend.

Viele kleine Änderungen

Drift passiert selten in einem dramatischen Moment. Er akkumuliert sich durch Hunderte kleiner Änderungen, von denen jede zu unbedeutend ist, um eine Dokumentationsaktualisierung zu rechtfertigen:

Eine Datei umbenennen
Ein Utility-Paket hinzufügen
Eine Bibliotheksabhängigkeit wechseln
Eine Funktion in ein separates Modul extrahieren

Keine einzelne Änderung ist bedeutsam genug, um ein Dokumentations-Update auszulösen. Zusammen transformieren sie die Architektur.

Teamfluktuation

Wenn Ingenieure gehen, nehmen sie implizites Wissen mit. Das neue Team erbt die Codebasis, aber nicht das Verständnis dafür, warum sie so strukturiert ist. Sie nehmen Änderungen basierend auf dem vor, was sie im Code sehen, nicht auf dem, was die Dokumentation sagt, und vergrößern damit den Drift.

Fehlende Feedback-Schleifen

Wenn niemand prüft, ob die Dokumentation mit der Realität übereinstimmt, ist Drift unsichtbar. Ohne einen Erkennungsmechanismus ist die einzige Möglichkeit, Drift zu entdecken, während eines Vorfalls, eines Audits oder wenn ein neuer Ingenieur darauf hinweist, dass das Diagramm nicht zum Code passt. Bis dahin kann der Drift erheblich sein.

Notfall-Änderungen

Produktionsvorfälle erfordern oft architektonische Abkürzungen: eine direkte Datenbankverbindung statt über die API-Schicht zu gehen, eine hardcodierte Konfiguration statt den Config Service zu nutzen, ein temporärer Cache, der permanent wird. Diese Änderungen umgehen normale Review-Prozesse und werden selten dokumentiert.

Die Kosten von Architecture Drift

Drift ist nicht nur ein ästhetisches Problem. Er hat konkrete, messbare Kosten.

Falsche Entscheidungen

Wenn Architekten Entscheidungen auf Basis veralteter Dokumentation treffen, können diese Entscheidungen falsch sein. "Dieser Service hat wenig Traffic, also können wir uns eine synchrone Abhängigkeit leisten" -- nur dass die Dokumentation veraltet ist und der Service tatsächlich 10x die dokumentierte Last bewältigt.

Langsames Onboarding

Neue Ingenieure verlassen sich auf Architekturdokumentation, um ihr mentales Modell aufzubauen. Wenn die Dokumentation falsch ist, bauen sie falsche mentale Modelle auf. Sie schreiben Code, der nicht zur tatsächlichen Architektur passt. Sie stellen Fragen, die ihre Verwirrung offenbaren und die Zeit erfahrener Ingenieure beanspruchen.

Incident Response

Während eines Produktionsvorfalls sollten Architekturdiagramme Teams helfen, den Blast Radius und die Abhängigkeiten zu verstehen. Wenn diese Diagramme falsch sind, verschwenden Teams wertvolle Minuten damit, die falschen Abhängigkeitsketten nachzuverfolgen oder kritische Upstream-Systeme zu übersehen.

Compliance- und Audit-Probleme

In regulierten Branchen wird Architekturdokumentation oft für Compliance benötigt (SOC 2, ISO 27001, HIPAA). Wenn Auditoren feststellen, dass die Dokumentation nicht mit der Realität übereinstimmt, ist das ein Befund -- möglicherweise ein schwerwiegender.

Verwirrung bei KI-Agenten

Da KI-Coding-Agenten immer verbreiteter werden, verlassen sie sich zunehmend auf Architekturdokumentation als Kontext. Ein Agent, der ein veraltetes C4-Modell liest, wird Code generieren, der zur dokumentierten Architektur passt, nicht zur tatsächlichen. Das verstärkt Drift, anstatt ihn zu beheben.

Wie man Architecture Drift erkennt

Fünf Ansätze sind gebräuchlich, und sie beantworten unterschiedliche Fragen. Die manuelle Überprüfung fragt, ob das Diagramm den Anwesenden im Raum noch richtig vorkommt. Fitness Functions und statische Analyse fragen, ob bestimmte Regeln verletzt werden. Die LLM-Bewertung fragt, ob sich der Code wie das Design liest, das er zu implementieren vorgibt. Drift Scoring fragt, wie viel vom dokumentierten Modell überhaupt noch existiert. Wählen Sie danach, welche Frage Sie gerade etwas kostet.

Manuelle Überprüfung (traditioneller Ansatz)

Der einfachste Ansatz ist eine regelmäßige manuelle Überprüfung: Das Team versammeln, die Architekturdiagramme durchgehen und prüfen, ob sie noch mit der Realität übereinstimmen.

Wann das funktioniert: Kleine Teams, einfache Architekturen, vierteljährlicher Rhythmus.

Wann das scheitert: Große Systeme, schnell arbeitende Teams oder wenn die Personen, die den Code am besten kennen, keine Zeit für Review-Meetings haben. Manuelle Überprüfung leidet auch unter Bestätigungsfehler -- Menschen neigen dazu, das zu sehen, was sie erwarten.

Architecture Fitness Functions

Fitness Functions, populär gemacht von Neal Ford und dem Buch "Building Evolutionary Architectures", sind automatisierte Tests, die architektonische Eigenschaften validieren:

// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
    packages := analyzeImports("./internal/handler/...")
    for _, pkg := range packages {
        for _, imp := range pkg.Imports {
            assert.NotContains(t, imp, "database/sql",
                "Handler %s imports database/sql directly", pkg.Name)
            assert.NotContains(t, imp, "gorm.io",
                "Handler %s imports GORM directly", pkg.Name)
        }
    }
}

Fitness Functions sind mächtig, um spezifische Regeln durchzusetzen, erfordern aber Vorabaufwand zum Schreiben und Pflegen. Sie prüfen Constraints, nicht das vollständige Modell.

Statische Analyse-Tools

Tools wie ArchUnit (Java), Deptrac (PHP) und go-arch-lint (Go) analysieren die Code-Struktur und setzen Abhängigkeitsregeln durch:

// go-arch-lint configuration
components:
  handler:
    in: ./internal/handler/
  service:
    in: ./internal/service/
  repository:
    in: ./internal/repository/

rules:
  handler:
    can_depend_on: [service]
  service:
    can_depend_on: [repository]
  repository:
    can_depend_on: []

Diese Tools sind hervorragend geeignet, um geschichtete Architektur innerhalb einer einzelnen Codebasis durchzusetzen. Sie adressieren nicht den serviceübergreifenden Drift und validieren nicht, dass das Architekturmodell mit dem Code übereinstimmt.

LLM-gestützte Bewertung

Thoughtworks hat die Reduzierung von Architecture Drift mit LLMs in den Assess-Ring des Technology Radar Vol. 34 (April 2026) aufgenommen. Ihre Formulierung des Problems ist zitierenswert, weil sie nicht von einem Anbieter stammt:

Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.

Auf Deutsch: Der zunehmende Einsatz von KI-Coding-Agenten kann den Drift von der beabsichtigten Codebasis und den Architektur-Designs beschleunigen. Unkontrolliert verstärkt sich dieser Drift, da Agenten und Menschen bestehende Patterns replizieren, auch die degradierten, und so eine Feedback-Schleife entsteht, in der schlechter Code noch schlechteren Code hervorbringt.

Die Technik, die sie beschreiben, kombiniert deterministische Analyse-Tools (sie nennen Spectral, ArchUnit und Spring Modulith) mit LLM-Bewertung, um semantische Verletzungen zu finden, die eine Regel-Engine nicht ausdrücken kann, und nutzt dann das LLM, um beim Beheben des Gefundenen zu helfen. Ihre Teams haben das auf API-Qualitätsrichtlinien angewandt und auf die Definition architektonischer Zonen, die von Agenten generierte Änderungen lenken.

Zwei ihrer Lektionen lohnen sich, unabhängig davon, welches Tool Sie verwenden. Ein erster Scan fördert mehr Verletzungen zutage, als irgendjemand triagieren wird -- Priorisierung ist also die eigentliche Arbeit. Und der Fix eines Agenten braucht seine eigene Verifikationsschleife, denn "es hat den Code geändert" und "es hat das System verbessert" sind zwei verschiedene Behauptungen.

Assess ist der Thoughtworks-Ring für "einen Blick wert, wir empfehlen es noch nicht". Behandeln Sie ihn genau so. Was er klärt, ist, dass das Problem real genug ist, damit eine große Beratung es aufschreibt -- und das ist mehr, als die meisten Drift-Argumente vorweisen können.

Automatisiertes Drift Scoring

Das ist der Ansatz, den Archyl verfolgt. Statt spezifische Regeln zu prüfen, validiert es das gesamte Architekturmodell gegen die Codebasis:

Stimmt jedes dokumentierte System mit einem Repository überein?
Stimmt jeder dokumentierte Container mit einem Verzeichnis in der Codebasis überein?
Verweist jedes dokumentierte Code Element auf eine Datei, die noch existiert?
Sind beide Endpunkte jeder dokumentierten Beziehung noch gültig?

Das Ergebnis ist ein Score von 0 bis 100 und eine Aufschlüsselung pro Element: was übereinstimmt, was dokumentiert, aber verschwunden ist, und was im Code existiert, aber nie festgehalten wurde. Wo Fitness Functions die Constraints prüfen, an deren Formulierung Sie gedacht haben, prüft das hier das gesamte Modell, das Sie ohnehin schon haben.

Die wichtigsten Design-Entscheidungen in Archyls Drift Detection:

Leichtgewichtig. Kein KI-Aufruf und keine abgerufenen Dateiinhalte. Ein rekursiver Tree-Request an Ihren Git-Provider, dann Pfad- und Namensabgleich gegen das Modell. Die Berechnung dauert Sekunden.

Deterministisch. Gleiche Codebasis, gleiches Modell, gleicher Score. Keine Variabilität durch LLM-Temperatur oder Prompt Engineering.

Günstig. Führen Sie es bei jedem Push ohne Kostenbedenken aus. Hundert Berechnungen am Tag sind kein Problem.

Umsetzbar. Die Aufschlüsselung benennt, welche Elemente abgedriftet sind, sodass Sie wissen, was zu reparieren ist.

Der Trade-off steckt im ersten Punkt. Pfade und Namen zu prüfen, statt Code zu lesen, macht den Score schnell, kostenlos und reproduzierbar -- und es bedeutet, dass die Prüfung strukturell ist. Sie sieht einen Container, dessen Verzeichnis weg ist, und ein Code Element, dessen Datei gelöscht wurde. Sie sieht nicht den REST-Aufruf, der zur Queue-Nachricht wurde, während beide Services ihre Namen behielten. Das ist verhaltensbezogener Drift, die eine Art in der Taxonomie am Anfang dieses Leitfadens, die keine günstige Prüfung erwischt. Manuelle Überprüfung und LLM-Bewertung sind das, was Sie dafür haben.

Wie der Drift Score im Detail berechnet wird behandelt die Formel, was aus dem Nenner ausgeschlossen wird und warum, und die übrigen Grenzen.

Den Kreislauf schließen

Erkennung allein ändert nichts. Ein Score, den jemand einmal berechnet und anschaut, ist ein Audit, keine Feedback-Schleife. Drei Mechanismen machen eine daraus, plus eine Unterscheidung, die man richtig ziehen sollte, bevor man irgendetwas davon verkabelt. Die Workflow-Praktiken, die daneben stehen -- Architecture as Code, Dokumentation in der Definition of Done, das Einführen von Conformance Rules -- sind Thema von lebendiger Architekturdokumentation.

Drift Detection in CI automatisieren

Der Mechanismus mit den schärfsten Zähnen ist ein CI-Gate, das fehlschlägt, wenn der Drift einen Schwellenwert überschreitet, denn es ist das einzige, das einen Merge stoppt:

on:
  push:
    branches: [main]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          threshold: '70'

Wenn der Build fehlschlägt, weil der Drift Score gesunken ist, muss jemand das Problem beheben, bevor gemergt werden kann. Dokumentationsgenauigkeit wird genauso nicht verhandelbar wie bestandene Tests.

Setzen Sie den Schwellenwert unter Ihren aktuellen Score, nicht auf die Zahl, die Sie gerne hätten. Ein Gate, das beim ersten Lauf fehlschlägt, wird beim ersten Lauf deaktiviert. Heben Sie ihn an, während das Team die Gewohnheit aufbaut.

Drift-Alerts einrichten

Archyl unterstützt Webhook-Alerts für Drift-Events:

drift.score_computed: Wird bei jeder Drift-Berechnung ausgelöst. An einen Slack-Channel posten für Sichtbarkeit.
drift.score_degraded: Wird ausgelöst, wenn der Score um 10+ Punkte fällt. Das ist Ihr Frühwarnsystem.

Konfigurieren Sie diese Alerts für einen Channel, den Ihr Team überwacht. Bewusstsein ist der erste Schritt zum Handeln.

Architektur-Reviews durchführen

Monatliche oder vierteljährliche Architektur-Reviews dienen mehreren Zwecken:

Validieren, dass die dokumentierte Architektur noch mit der Realität übereinstimmt
Drift identifizieren, den automatisierte Tools übersehen haben (z. B. verhaltensbezogener Drift)
Diskutieren, ob abgedriftete Komponenten im Code oder in der Dokumentation aktualisiert werden sollten
ADRs für Entscheidungen überprüfen und aktualisieren, die möglicherweise überdacht werden müssen

Verwechseln Sie Drift nicht mit Conformance

Die beiden werden oft genug zusammen ausgeführt, dass es sich lohnt, sie zu trennen, denn sie werden unterschiedlich berechnet und sie schlagen aus unterschiedlichen Gründen fehl.

Drift Detection fragt, ob Ihr Modell mit der Realität übereinstimmt. Sie vergleicht die dokumentierte Architektur mit dem Repository und produziert einen Score.

Conformance Rules fragen, ob die Realität Ihren Regeln folgt: Der Frontend-Container darf nicht vom Datenbank-Container abhängen, jede öffentliche API läuft über das Gateway, jeder Service besitzt seine eigene Datenbank. Ein Conformance-Check kann auf einem Modell bestehen, das schwer abgedriftet ist, und ein perfekt akkurates Modell kann jede Regel verletzen, die Sie haben.

Sie wollen beides, und Sie sollten die eine Zahl nicht so lesen, als wäre sie die andere.

Architecture Drift vs. Architecture Erosion

Diese Begriffe sind verwandt, aber unterschiedlich:

Architecture Drift ist die Divergenz zwischen Dokumentation und Implementierung. Der Code könnte völlig in Ordnung sein -- die Dokumentation ist nur falsch.

Architecture Erosion ist die Degradation der Architektur selbst. Der Code verletzt architektonische Prinzipien, akkumuliert Technical Debt und wird schwerer zu warten. Erosion ist ein Code-Qualitätsproblem. Drift ist ein Problem der Dokumentationsgenauigkeit.

Perry und Wolf zogen die Linie 1992 an einer anderen Stelle: Für sie waren beide Eigenschaften des Systems und nicht der Dokumentation, wobei Erosion durch die Verletzung der Architektur entstand und Drift durch Unempfindlichkeit ihr gegenüber. Der moderne Sprachgebrauch ist lockerer und für ein arbeitendes Team nützlicher, aber wenn Sie die akademische Literatur zu Architecture Erosion lesen, rechnen Sie damit, dass die Begriffe dort anders liegen als hier.

Sie treten oft gemeinsam auf. Wenn Dokumentation abdriftet, verlieren Teams das Bewusstsein für die beabsichtigte Architektur. Ohne dieses Bewusstsein nehmen sie Änderungen vor, die die Architektur erodieren. Drift ermöglicht Erosion.

Deshalb ist Drift Detection über die reine Dokumentationsgenauigkeit hinaus wichtig. Akkurate Dokumentation dient als Referenz, die Erosion verhindert. Wenn jeder die beabsichtigte Architektur sehen kann, ist die Wahrscheinlichkeit größer, dass sie sie einhalten.

Drift im Zeitverlauf messen und verfolgen

Ein einzelner Drift Score ist nützlich. Ein Trend ist mächtig.

Baseline etablieren

Führen Sie die erste Berechnung durch, bevor Sie irgendetwas an der Arbeitsweise des Teams ändern. Was auch immer herauskommt, ist Ihre Baseline, und eine niedrige erste Zahl ist eine Information, kein Urteil. Dokumentation, die zu pflegen niemand beauftragt war, ist nicht gescheitert; sie war bloß ungemessen.

Widerstehen Sie dem Impuls, vor dem ersten Lauf noch schnell etwas zu reparieren. Sie wollen die Zahl, die die Situation beschreibt, in der Sie tatsächlich stecken, nicht die, die Sie nach einem Aufräum-Wochenende bekommen.

Den Trend verfolgen

Ein einzelner Score ist eine Tatsache über heute. Der Trend ist das, was Ihnen sagt, ob irgendetwas, das Sie geändert haben, gewirkt hat:

Wird der Drift im Laufe der Zeit besser oder schlechter?
Hat ein bestimmter Sprint oder Release einen Abfall verursacht?
Hält der CI-Schwellenwert die Linie, oder senkt ihn einfach jeder?

Archyl speichert jede Berechnung mit ihrer vollständigen Aufschlüsselung, sodass ein historischer Report wieder geöffnet und Element für Element verglichen werden kann. Welches Tool Sie auch nutzen: Behalten Sie die Historie. Ein Drift Score, den Sie jedes Quartal von Grund auf neu berechnen und dann wegwerfen, ist wieder ein Audit.

Setzen Sie ein Ziel, das Sie auch halten können

Wählen Sie die nächste Zahl statt der idealen. Wenn heute 58 steht, ist 65 das nützliche Ziel und die nützliche Diskussion dreht sich darum, welche fünf Elemente Sie dorthin bringen. Ein Team, das sich darauf einigt, bis Quartalsende 90 % zu erreichen, einigt sich meistens auf gar nichts.

Die Rolle der Drift Detection in der KI-gestützten Entwicklung

Das ist der Teil, der sich zuletzt am stärksten verändert hat, und deshalb hat Thoughtworks den oben zitierten Eintrag geschrieben: Agenten replizieren die Patterns, die sie vorfinden, degradierte eingeschlossen, sodass Drift, der sich früher im Tempo menschlicher Commits ansammelte, sich jetzt im Tempo generierter Commits ansammelt.

KI-Agenten verlassen sich zunehmend auf Architekturdokumentation als Kontext. Über Protokolle wie MCP können Agenten Ihr C4-Modell, ADRs und Conformance Rules lesen, bevor sie Code generieren. Das macht sie effektiver -- sie generieren Code, der zu Ihrer Architektur passt, statt zu raten.

Aber das funktioniert nur, wenn die Dokumentation akkurat ist. Ein Agent, der ein veraltetes C4-Modell liest und darauf basierend Code generiert, wird Code produzieren, der zur falschen Architektur passt. Der Agent verstärkt den Drift, statt ihn zu verhindern.

Drift Detection schafft die Feedback-Schleife, die KI-Agenten ehrlich hält:

Agent liest Architektur via MCP
Agent generiert Code, der zur dokumentierten Architektur passt
Code wird gemergt, was möglicherweise die tatsächliche Architektur ändert
Drift Detection läuft und erkennt jede Abweichung
CI-Gate schlägt fehl, wenn Drift den Schwellenwert überschreitet
Team aktualisiert Dokumentation, um die Realität widerzuspiegeln
Agent liest aktualisierte Architektur -- Kreislauf schließt sich

Ohne Schritt 4 ist der Kreislauf offen. Dokumentation wird zunehmend fiktiv. Agenten generieren zunehmend Code, der zu einer Fantasie-Architektur passt. Die Lücke vergrößert sich mit jedem Commit.

Drift Detection ist der Mechanismus, der diesen Kreislauf schließt.

Erste Schritte mit Drift Detection

Wenn Sie irgendwo bereits ein Modell haben

Messen Sie es, bevor Sie sonst irgendetwas ändern. Das ist der billigste erste Schritt, den es gibt, und er verpflichtet Sie zu nichts.

Wenn Ihre Architektur bereits in Structurizr DSL, LikeC4, IcePanel oder einem Backstage-Katalog lebt, holen Sie das Modell herüber und berechnen Sie einen Score dagegen, so wie es ist. Sie messen die Dokumentation, die Sie ohnehin geschrieben haben, in dem Zustand, in dem Sie sie hinterlassen haben. Keine Workflow-Änderung, keine neue Gewohnheit fürs Team, noch keine Entscheidung über Tooling. Die Zahl ist der Input für diese Entscheidung, nicht ihr Ergebnis.

Zwei ehrliche Vorbehalte. Die Importer sind nicht verlustfrei: Views, Styles und Layout überleben nicht, und der Structurizr-Parser überspringt Deployment-Umgebungen und Deployment-Knoten, benennt sie aber mit Zeilennummer in seiner Warnliste -- lesen Sie diese Liste und das importierte Modell also, bevor Sie dem Nenner trauen. Und der Score beschreibt das Modell, das angekommen ist, nicht die Datei, die Sie exportiert haben.

Was zurückkommt, ist eine Liste pro Element. Ein Score von 84 ist ein Wartungsproblem, das Sie einplanen können. Ein Score von 41 heißt, dass Entscheidungen gegen ein Dokument getroffen wurden, das ein anderes System beschreibt -- und das erfährt man besser jetzt als beim nächsten Vorfall.

Wenn Sie keine Architekturdokumentation haben

Starten Sie mit der KI-Discovery. Verbinden Sie ein Repository, lassen Sie die Discovery das C4-Modell vorschlagen und genehmigen oder verwerfen Sie ihre Vorschläge, statt selbst zu zeichnen. Sobald es ein Modell gibt, ist Drift Detection das, was es ehrlich hält.

Wenn Sie Drift bereits verfolgen

Bringen Sie sie in die CI. Setzen Sie einen Schwellenwert unter Ihren aktuellen Score. Konfigurieren Sie den Degradations-Alert. Machen Sie Drift zu einer Metrik, die das Team wöchentlich sieht, nicht zu einer Zahl, die eine Person vor einem Review berechnet.

Unabhängig vom Ausgangspunkt

Drift verzinst sich wie Technical Debt: Je länger Sie ihn liegen lassen, desto mehr gibt es abzugleichen und desto weniger vertraut in der Zwischenzeit noch jemand dem Dokument. Der Unterschied ist, dass Sie herausfinden können, wo Sie heute stehen, ohne vorher irgendetwas zu reparieren.

Ihre Architekturdokumentation spiegelt entweder die Realität wider oder sie tut es nicht. Der Sinn eines Drift Scores ist, dass Sie nicht mehr raten müssen, was von beidem zutrifft.

Tiefer einsteigen: wie der Drift Score berechnet wird für den Mechanismus, lebendige Architekturdokumentation für die Praktiken, die ein Modell wahr halten, und was ist das C4-Modell, falls Sie bei null anfangen. Definitionen: Architecture Drift, Living Documentation und Drift Detection im Produkt. Der Developer-Plan ist kostenlos und braucht keine Karte, falls Sie die Dokumentation, die Sie schon haben, in eine Zahl fassen wollen: archyl.com.

Architecture Drift Detection: Code und Design im Einklang halten - Archyl Blog