Architecture Drift Score: Sagt Ihre Dokumentation die Wahrheit?

Eine Metrik, die niemand prüfen kann, ist eine Metrik, nach der niemand handeln sollte. Deshalb geht es in diesem Beitrag um die Arithmetik: wie der Architecture Drift Score entsteht, was im Nenner landet, was wir bewusst weglassen und die vier Dinge, die die Prüfung nicht sehen kann.

Der Score beantwortet eine Frage. Welcher Prozentsatz Ihrer dokumentierten Architektur existiert noch in Ihrer Codebase? Es ist eine Zahl von 0 bis 100, berechnet aus einer einzigen Anfrage an Ihren Git-Provider, ohne KI im Ablauf und ohne dass Dateiinhalte gelesen werden.

Wenn Sie das Problem statt der Arithmetik suchen: der Leitfaden zu Architecture Drift behandelt, was Drift ist, warum er entsteht und welche anderen Wege es gibt, ihn zu erkennen. Fangen Sie dort an und kommen Sie zurück. Diese Seite setzt voraus, dass Sie eine Zahl bereits wollen und wissen möchten, ob Sie ihr glauben können.

Die Zahl lesen

Öffnen Sie ein beliebiges Projekt in Archyl, klicken Sie auf das Herzschlag-Symbol in der Kopfzeile und drücken Sie "Compute Drift Score". In wenigen Sekunden erhalten Sie eine Zahl:

• 90-100% — Ausgezeichnet. Ihre Dokumentation stimmt eng mit der Codebase überein.
• 70-89% — Gut. Größtenteils korrekt, einige Lücken zu schließen.
• 50-69% — Mäßig. Signifikanter Drift erkannt. Zeit für ein Update.
• Unter 50% — Ihre Dokumentation ist Fiktion.

Diese Bänder sind unser Urteil darüber, was es wert ist, dass man handelt, und keine Messung von irgendetwas. Die Zahl darunter ist exakt.

Wie die Zahl berechnet wird

Jedes Element in Ihrem Modell wird in einen Bucket einsortiert, und der Score ist der Anteil, der überlebt hat:

score = floor( (matched + 0.5 × partial) / total × 100 )

total = matched + partial + missing_in_code + new_in_code

• matched — das Modell sagt, es existiert, das Repository stimmt zu.
• missing_in_code — dokumentiert und nicht gefunden. Ein Container, dessen Verzeichnis verschwunden ist; ein Code-Element, dessen Datei gelöscht wurde.
• new_in_code — im Repository gefunden, im Modell nicht vorhanden. Undokumentiert, was Drift in die andere Richtung ist und exakt genauso hart gegen Sie zählt.

partial zählt halb und ist Elementen vorbehalten, die mit Abweichungen übereinstimmen. Die heutigen Prüfungen erzeugen es nicht: Jedes Element landet in einer der anderen drei Kategorien, in der Praxis ist der Score also der Anteil von matched. Wir sagen es Ihnen, weil eine Formel mit einem Term, der nie feuert, genau die Art von Sache ist, die Sie von uns hören sollten, statt sie zu entdecken.

Zwei Details, die zählen, wenn Sie zwei Läufe vergleichen. Das Ergebnis wird abgeschnitten, nicht gerundet, 89,9 wird also als 89 ausgewiesen. Und undokumentierte Elemente vergrößern den Nenner, weshalb drei neue Services, die Sie nicht dokumentieren, Ihren Score senken, obwohl nichts von dem, was Sie geschrieben hatten, unwahr geworden ist.

Was tatsächlich geprüft wird

Die Drift-Analyse ist bewusst leichtgewichtig: eine rekursive Tree-Anfrage an Ihren Git-Provider, keine KI, keine abgerufenen Dateiinhalte. Sie validiert Ihre Architektur in fünf Dimensionen:

Systems — Stimmt Ihr Repository-Name mit dem dokumentierten System überein? Wir verwenden dieselbe PascalCase-Namenskonvention wie die KI-Discovery-Pipeline, mit Fuzzy-Matching, sodass EkoAuthz zu einem Repository namens authz passt.

Containers — Entsprechen die Top-Level-Verzeichnisse in Ihrem Repository den dokumentierten Containers? frontend/ passt zu FrontendWebApp. backend/ passt zu BackendApiServer. Infrastruktur-Container (Datenbanken, Queues, Monitoring), die keine Quellverzeichnisse haben, werden ausgeschlossen, weil sie valide Dokumentation externer Dienste sind und kein Drift. Der nächste Abschnitt behandelt, was dieser Ausschluss kostet.

Components — Sind die Components unter jedem Container noch gültig? Wenn das Verzeichnis des übergeordneten Containers existiert, werden seine Components als gültig angenommen. Wenn das Container-Verzeichnis verschwunden ist, werden alle seine Components markiert.

Code Elements — Das ist die präziseste Prüfung. Jedes Code-Element in Ihrem C4 model hat einen filePath. Wir überprüfen, ob jede Datei noch im Repository existiert. Datei umbenannt? Klasse gelöscht? Modul verschoben? Der Drift Score erkennt es sofort.

Relationships — Eine Beziehung ist gültig, wenn sowohl ihr Quell- als auch ihr Zielelement die Validierung bestanden haben. Wenn einer der Endpunkte gedriftet ist, wird die Beziehung markiert.

Das Ergebnis ist eine Aufschlüsselung pro Element, die genau zeigt, was übereinstimmt, was fehlt und was neu ist — kein undurchsichtiger Score, sondern ein handlungsrelevanter Bericht.

Was aus dem Nenner ausgeschlossen wird

Ein Score ist nur so ehrlich wie die Dinge, die er zu zählen verweigert. Drei Ausschlüsse, alle bewusst:

Externe Systeme und Personen. Alles, was als externes System oder als Person typisiert ist, wird vor dem Vergleich auf beiden Seiten entfernt. Stripe, Ihr Identity Provider und "Kunde" gehören auf ein System-Context-Diagramm, und keines davon wird jemals in Ihrem Repository auftauchen. Sie als fehlend zu zählen, würde Sie dafür bestrafen, dass Sie ein korrektes Diagramm gezeichnet haben.

Infrastruktur-Container ohne Quellverzeichnis. Ein dokumentierter Container, der zu keinem Verzeichnis passt, wird aus der Container-Zählung entfernt, statt als Drift gezählt zu werden. Ihre PostgreSQL-Instanz, Ihr Kafka-Cluster und Ihr Datadog-Account sind legitime Container, und keiner davon ist ein Ordner.

Diese Regel hat einen Preis, und Sie sollten ihn kennen: Ein echtes Service-Verzeichnis, das Sie gelöscht haben, wird ebenfalls aus der Container-Zählung ausgeschlossen, weil die Prüfung "Datenbank" nicht von "Service, den wir letzten Sprint entfernt haben" unterscheiden kann. Seine Components sind nicht ausgeschlossen. Sie werden weiterhin als fehlend aufgelöst, weil ihr übergeordneter Container nicht übereingestimmt hat, ein entfernter Service taucht also sehr wohl im Score auf — eine Ebene tiefer, als Sie ihn erwarten würden.

Code-Elemente ohne hinterlegten Dateipfad. Wenn ein Code-Element in Ihrem Modell keinen filePath hat, gibt es nichts zu verifizieren, es wird also übersprungen statt geraten. Es zählt weder für noch gegen Sie. Generierte und mitgelieferte Pfade (vendor/, node_modules/, dist/, target/, __pycache__/ und der Rest der üblichen Liste) werden aus dem Dateibaum gefiltert, bevor irgendetwas davon läuft.

Warum Leichtgewichtigkeit wichtig ist

Wir haben uns bewusst dagegen entschieden, die vollständige KI-Discovery-Pipeline für die Drift-Erkennung auszuführen. Hier ist der Grund:

Geschwindigkeit. Die KI-Analyse dauert bei großen Repositories Minuten. Die Drift-Bewertung dauert Sekunden. Sie können sie bei jedem Push ausführen, ohne Ihre Pipeline zu verlangsamen.

Determinismus. KI kann bei derselben Codebase unterschiedliche Ergebnisse liefern, abhängig von Modelltemperatur, Prompt-Variationen und Token-Limits. Die Existenz eines Dateipfads ist binär — entweder ist die Datei da oder nicht. Ihr Score ist reproduzierbar.

Kosten. Keine KI-Tokens verbraucht. Keine API-Rate-Limits erreicht. Führen Sie es hundertmal am Tag aus, wenn Sie möchten.

Einfachheit. Der Algorithmus ist auditierbar. Dateipfade prüfen, Verzeichnisnamen abgleichen, Beziehungen verifizieren. Keine Black Box.

Was der Score nicht sehen kann

Jede dieser Eigenschaften wird mit demselben Tausch erkauft: Die Prüfung liest Struktur, nicht Code. Vier Konsequenzen, und keine davon ist ein Bug, den wir verbergen wollen.

Verhaltensdrift ist unsichtbar. Wenn zwei Services ihre Namen und ihre Verzeichnisse behalten, während der synchrone HTTP-Aufruf zwischen ihnen zu einer Queue-Nachricht wird, bewegt sich der Score nicht. Strukturell hat sich nichts geändert. Das ist der größte blinde Fleck, und es gibt keine billige Lösung dafür: Ihn zu erkennen bedeutet, Code zu lesen oder das Modell mit Menschen durchzugehen.

Eine Verschiebung sieht exakt aus wie eine Löschung. Code-Elemente werden über den exakten, case-sensitiven Dateipfad validiert. Verschieben Sie internal/auth/token.go nach internal/identity/token.go, ohne eine einzige Zeile darin anzufassen, und das Element wird als fehlend gemeldet. Das ist technisch korrekt, denn der dokumentierte Pfad ist falsch, und es bedeutet, dass ein Refactoring, das Verzeichnisse umbenennt, Ihren Score auf eine Weise senkt, die alarmierend aussieht und sich mit einer einzeiligen Änderung pro Element auflöst.

Genauigkeit auf Component-Ebene wird geerbt, nicht verifiziert. Wenn das Verzeichnis eines Containers existiert, wird jede Component darunter als gültig angenommen. Die Prüfung schaut nie hinein. Ein Container, der noch existiert, aber ausgeweidet und neu geschrieben wurde, wird auf Component-Ebene also als sauber bewertet, und die Zahl ist Ihrem Level-3-Diagramm gegenüber zuversichtlicher, als die Belege es hergeben.

Der Namensabgleich ist großzügig. Systems und Containers werden in drei Durchgängen über den Namen abgeglichen: exakt ohne Berücksichtigung der Groß-/Kleinschreibung, dann Teilstring-Enthaltensein in beide Richtungen, dann überlappende Tokens nach dem Aufteilen von PascalCase und kebab-case. EkoAuthz passt zu einem Repository namens authz; BackendApiServer passt zu einem Verzeichnis namens backend. Das ist es, was verhindert, dass triviale Namensunterschiede als Drift gemeldet werden, und es irrt in die Richtung, Ihrem Modell im Zweifel Recht zu geben. Wenn Sie eine strenge Lesart wollen, verwenden Sie die Aufschlüsselung pro Element statt der Schlagzeilenzahl.

Zusammengenommen ist der Score ein gutes Maß dafür, ob Ihr Modell noch dasselbe System beschreibt, und ein schwaches Maß dafür, ob es es korrekt beschreibt. Behandeln Sie einen hohen Score als "keine strukturellen Überraschungen", nicht als "die Dokumentation ist richtig".

Trends verfolgen, nicht nur Momentaufnahmen

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

Jede Drift-Berechnung wird mit ihrer vollständigen Aufschlüsselung gespeichert. Der Overview-Tab zeigt ein Balkendiagramm Ihres Scores im Zeitverlauf. Klicken Sie auf einen beliebigen Balken, um diesen historischen Bericht zu laden und genau zu sehen, was sich geändert hat.

Das macht aus der Drift-Bewertung statt eines einmaligen Audits eine kontinuierliche Gesundheitsmetrik. Sie können sehen:

• Hat das Refactoring der letzten Woche die Dokumentationsgenauigkeit verbessert oder verschlechtert?
• Wird der Drift mit der Zeit schlimmer, und hat irgendetwas, das Sie am Workflow geändert haben, ihn verlangsamt?
• Welcher Sprint hat die meisten undokumentierten Änderungen eingeführt?

Setzen Sie ihn in der CI durch

Eine Metrik, die Sie nicht durchsetzen, ist eine Metrik, die Sie ignorieren werden. Deshalb haben wir eine GitHub Action gebaut.

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'

Setzen Sie threshold: '70' und die Action schlägt fehl, wenn Ihre Architekturdokumentation unter 70% Genauigkeit fällt. Die Job-Zusammenfassung zeigt eine formatierte Tabelle mit der vollständigen Aufschlüsselung — direkt in Ihren PR-Checks sichtbar.

Sie können den Score auch als PR-Kommentar posten:

- uses: archyl-com/actions/drift-score@v1
  id: drift
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'

- uses: actions/github-script@v7
  if: github.event_name == 'pull_request'
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '## Architecture Drift: ' +
              '${{ steps.drift.outputs.score }}%\n' +
              'Matched: ${{ steps.drift.outputs.matched-count }}' +
              ' / ${{ steps.drift.outputs.total-elements }}'
      })

Jeder Entwickler sieht die Drift-Auswirkung seiner Änderungen vor dem Merge. Architekturdokumentation wird zum Bürger erster Klasse in Ihrer CI-Pipeline — neben Tests, Linting und Security-Scans.

MCP: KI-Agenten, die ihre Genauigkeit kennen

Wenn Sie Claude Code, Cursor oder einen beliebigen MCP-kompatiblen KI-Agenten mit Archyls MCP-Server verwenden, steht die Drift-Bewertung als Tool zur Verfügung:

compute_drift_score({ projectId: "..." })
get_drift_score({ projectId: "..." })
get_drift_history({ projectId: "..." })
get_drift_details({ scoreId: "..." })

Das bedeutet, ein KI-Agent kann die Dokumentationsgenauigkeit prüfen, bevor er zu arbeiten beginnt. Das Tool get_agent_context liefert bereits das vollständige C4 model, ADRs und Conformance-Regeln. Jetzt kann es auch prüfen, wie vertrauenswürdig diese Dokumentation ist.

Ein Agent, der einen Drift Score von 45% sieht, weiß, dass er mit dem erhaltenen Architekturkontext vorsichtig sein muss. Ein Agent, der 95% sieht, kann sich zuversichtlich auf die dokumentierte Struktur verlassen. Das ist die Grundlage für selbstbewusste KI-Agenten, die ihr Verhalten an die Dokumentationsqualität anpassen.

Webhook-Alerts: Erfahren Sie, wenn Drift passiert

Zwei neue Webhook-Events halten Sie informiert, ohne dass Sie Dashboards prüfen müssen:

• drift.score_computed — Wird jedes Mal ausgelöst, wenn ein Drift Score fertig berechnet ist. Schieben Sie es für mehr Sichtbarkeit in einen Slack-Channel.
• drift.score_degraded — Wird ausgelöst, wenn der Score gegenüber der vorherigen Berechnung um 10 oder mehr Punkte fällt. Das ist Ihr Frühwarnsystem — die Architektur driftet schnell.

Konfigurieren Sie diese in Archyls Webhook-Einstellungen. Sie funktionieren mit Slack, Microsoft Teams, Discord und jedem generischen HTTP-Endpunkt.

Die REST API

Für Teams, die vollständige programmatische Kontrolle wollen:

# Berechnung auslösen
curl -X POST https://api.archyl.com/api/v1/drift/compute \
  -H "X-API-Key: $API_KEY" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "your-project-uuid"}'

# Neuesten Score abrufen
curl https://api.archyl.com/api/v1/drift/latest?projectId=...

# Score-Verlauf abrufen
curl https://api.archyl.com/api/v1/drift/history?projectId=...&limit=20

Die Berechnung ist asynchron — der POST kehrt sofort mit einer Score-ID zurück, und Sie pollen, bis status auf completed steht. Die GitHub Action erledigt das automatisch.

Wo das in der Schleife sitzt

Ein Score ist ein Schritt in einem Kreislauf: Agenten und Menschen lesen das Modell, Code ändert sich, der Score misst die Lücke, die CI hält eine Schwelle, das Team gleicht ab. Ohne den Messschritt hat der Kreislauf keine Rückkopplung, und die Dokumentation driftet unwidersprochen. Dieses Argument und den Rest der Begründung, Drift überhaupt zu erkennen, finden Sie im Leitfaden.

Wofür dieser Beitrag verantwortlich ist, ist die Vertrauenswürdigkeit des Messschritts. Daher die Formel, die Ausschlüsse und die vier Dinge, die er nicht sehen kann.

Erste Schritte

1. Öffnen Sie ein beliebiges Projekt in Archyl
2. Klicken Sie auf das Herzschlag-Symbol in der Kopfzeilen-Toolbar
3. Klicken Sie auf "Compute Drift Score"
4. Richten Sie die GitHub Action für kontinuierliches Monitoring ein
5. Konfigurieren Sie einen Slack-Webhook für drift.score_degraded-Alerts

Ihre Architekturdokumentation spiegelt entweder die Realität wider oder nicht. Jetzt haben Sie eine Zahl, die Ihnen sagt, welches von beidem zutrifft — und genug von ihrer Arithmetik, um mit ihr zu streiten.

Der Rest des Clusters: Architecture Drift Detection für das Problem und die anderen Erkennungsmethoden, Living Architecture Documentation für die Praktiken, die verhindern, dass ein Score wieder abrutscht. Definitionen: Architecture Drift. Produktseite: Drift Detection.