Architekturdokumentation luegt. Nicht absichtlich -- sie hoert einfach auf, wahr zu sein, sobald sich der Code aendert. Heute stellen wir den Architecture Drift Score vor: eine einzelne Zahl, die Ihnen zeigt, wie genau Ihr C4 model Ihre tatsaechliche Codebase widerspiegelt. In Sekunden berechnet, ueber die Zeit verfolgt und in der CI durchsetzbar.

Architecture Drift Score: Sagt Ihre Dokumentation die Wahrheit?

Es gibt ein schmutziges Geheimnis in der Softwarearchitektur: Die meiste Dokumentation ist falsch.

Nicht falsch wie "enthaelt Fehler". Falsch wie "beschreibt ein System, das nicht mehr existiert". Das Diagramm zeigt einen Microservice, der vor sechs Monaten mit einem anderen zusammengefuehrt wurde. Das C4 model listet einen Redis-Cache auf, der waehrend eines Wochenend-Vorfalls durch Memcached ersetzt wurde. Das Komponentendiagramm verweist auf ein PaymentGateway, das bei einem Refactoring in BillingService umbenannt wurde, von dem niemand den Architekten informiert hat.

Das ist kein Disziplinproblem. Es ist ein strukturelles Problem. Code aendert sich kontinuierlich. Dokumentation aendert sich, wenn sich jemand daran erinnert. Die Luecke zwischen Realitaet und Dokumentation -- das, was wir Architecture Drift nennen -- waechst still, bis das Diagramm an der Wand keinerlei Aehnlichkeit mehr mit dem System in Produktion hat.

Wir haben den Drift Score entwickelt, um diese Luecke sichtbar, messbar und handlungsrelevant zu machen.

Eine einzelne Zahl: 0 bis 100

Der Architecture Drift Score beantwortet eine Frage: Welcher Prozentsatz Ihrer dokumentierten Architektur existiert tatsaechlich in Ihrer Codebase?

Oeffnen Sie ein beliebiges Projekt in Archyl, klicken Sie auf das Herzschlag-Symbol in der Kopfzeile und druecken Sie "Compute Drift Score". In wenigen Sekunden sehen Sie eine Zahl zwischen 0 und 100:

90-100% -- Ausgezeichnet. Ihre Dokumentation stimmt eng mit der Codebase ueberein.
70-89% -- Gut. Groesstenteils korrekt, einige Luecken zu schliessen.
50-69% -- Maessig. Signifikanter Drift erkannt. Zeit fuer ein Update.
Unter 50% -- Ihre Dokumentation ist Fiktion.

Das war's. Kein langer Bericht zum Lesen. Keine subjektive Bewertung. Eine Zahl, die Sie verfolgen, analysieren und durchsetzen koennen.

Was tatsaechlich geprueft wird

Die Drift-Analyse ist bewusst leichtgewichtig -- ein einziger API-Aufruf an Ihren Git-Provider, keine KI, kein Dateiinhalt abgerufen. Sie validiert Ihre Architektur in fuenf Dimensionen:

Systems -- Stimmt Ihr Repository-Name mit dem dokumentierten System ueberein? Wir verwenden dieselbe PascalCase-Namenskonvention wie die KI-Discovery-Pipeline, mit Fuzzy-Matching, sodass EkoAuthz einem Repository namens authz zugeordnet wird.

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 korrekt ausgeschlossen -- sie sind valide Dokumentation externer Dienste, kein Drift.

Components -- Sind die Komponenten unter jedem Container noch gueltig? Wenn das Verzeichnis des uebergeordneten Containers existiert, werden seine Komponenten als gueltig angenommen. Wenn das Container-Verzeichnis verschwunden ist, werden alle seine Komponenten markiert.

Code Elements -- Das ist die praeziseste Pruefung. Jedes Code-Element in Ihrem C4 model hat einen filePath. Wir ueberpruefen, ob jede Datei noch im Repository existiert. Datei umbenannt? Klasse geloescht? Modul verschoben? Der Drift Score erkennt es sofort.

Relationships -- Eine Beziehung ist gueltig, 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 Aufschluesselung pro Element, die genau zeigt, was uebereinstimmt, was fehlt und was neu ist -- kein undurchsichtiger Score, sondern ein handlungsrelevanter Bericht.

Warum Leichtgewichtigkeit wichtig ist

Wir haben uns bewusst dagegen entschieden, die vollstaendige KI-Discovery-Pipeline fuer die Drift-Erkennung auszufuehren. Hier ist der Grund:

Geschwindigkeit. Die KI-Analyse dauert Minuten bei grossen Repositories. Die Drift-Bewertung dauert Sekunden. Sie koennen sie bei jedem Push ausfuehren, ohne Ihre Pipeline zu verlangsamen.

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

Kosten. Keine KI-Tokens verbraucht. Keine API-Rate-Limits erreicht. Fuehren Sie es hundertmal am Tag aus, wenn Sie moechten.

Einfachheit. Der Algorithmus ist auditierbar. Dateipfade pruefen, Verzeichnisnamen abgleichen, Beziehungen verifizieren. Keine Black Box.

Verfolgen Sie Trends, nicht nur Momentaufnahmen

Ein einzelner Score ist nuetzlich. Ein Trend ist maechtig.

Jede Drift-Berechnung wird mit ihrer vollstaendigen Aufschluesselung gespeichert. Der Overview-Tab zeigt ein Balkendiagramm Ihres Scores im Zeitverlauf. Klicken Sie auf einen beliebigen Balken, um den historischen Bericht zu laden und genau zu sehen, was sich geaendert hat.

Das verwandelt das Drift-Scoring von einem einmaligen Audit in eine kontinuierliche Gesundheitsmetrik. Sie koennen sehen:

Hat das Refactoring der letzten Woche die Dokumentationsgenauigkeit verbessert oder verschlechtert?
Wird der Drift ueber die Zeit schlimmer? (Spoiler: Ohne Automatisierung immer.)
Welcher Sprint hat die meisten undokumentierten Aenderungen eingefuehrt?

Setzen Sie es in der CI durch

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

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 schlaegt fehl, wenn die Genauigkeit Ihrer Architekturdokumentation unter 70% faellt. Die Job-Zusammenfassung zeigt eine formatierte Tabelle mit der vollstaendigen Aufschluesselung -- direkt sichtbar in Ihren PR-Checks.

Sie koennen 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 Aenderungen vor dem Merge. Architekturdokumentation wird zum First-Class-Citizen in Ihrer CI-Pipeline -- neben Tests, Linting und Sicherheitsscans.

MCP: KI-Agenten, die ihre Genauigkeit kennen

Wenn Sie Claude Code, Cursor oder einen MCP-kompatiblen KI-Agenten mit Archyls MCP-Server verwenden, ist das Drift-Scoring als Tool verfuegbar:

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

Das bedeutet, ein KI-Agent kann die Dokumentationsgenauigkeit ueberpruefen, bevor er mit der Arbeit beginnt. Das Tool get_agent_context liefert bereits das vollstaendige C4 model, ADRs und Konformitaetsregeln. Jetzt kann es auch die Vertrauenswuerdigkeit dieser Dokumentation ueberpruefen.

Ein Agent, der einen Drift Score von 45% sieht, weiss, dass er mit dem erhaltenen Architekturkontext vorsichtig sein sollte. Ein Agent, der 95% sieht, kann sich zuversichtlich auf die dokumentierte Struktur verlassen. Dies ist die Grundlage fuer selbstbewusste KI-Agenten, die ihr Verhalten basierend auf der Dokumentationsqualitaet anpassen.

Webhook-Benachrichtigungen: Erfahren Sie, wenn Drift auftritt

Zwei neue Webhook-Events halten Sie informiert, ohne dass Sie Dashboards ueberpruefen muessen:

drift.score_computed -- Wird jedes Mal ausgeloest, wenn eine Drift-Score-Berechnung abgeschlossen ist. Leiten Sie es an einen Slack-Kanal weiter fuer Transparenz.
drift.score_degraded -- Wird ausgeloest, wenn der Score um 10 oder mehr Punkte gegenueber der vorherigen Berechnung sinkt. Das ist Ihr Fruehwarnsystem -- die Architektur driftet schnell.

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

Die REST API

Fuer Teams, die volle programmatische Kontrolle wuenschen:

# Berechnung ausloesen
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 zurueck, und Sie pollen, bis status zu completed wird. Die GitHub Action handhabt dies automatisch.

Was das fuer die agentische Aera bedeutet

Wir treten in eine Aera ein, in der KI-Agenten einen erheblichen Teil des Produktionscodes schreiben. Diese Agenten sind schnell, leistungsfaehig und kontextblind. Sie wissen nicht, dass der AuthService letzten Monat in IdentityService und AccessControl aufgeteilt wurde. Sie wissen nicht, dass das Verzeichnis frontend/ in web/ umbenannt wurde.

Der Drift Score erzeugt eine Rueckkopplungsschleife:

KI-Agent liest das C4 model via MCP, bevor er Code schreibt.
Code-Aenderungen geschehen (durch Menschen oder Agenten).
Drift Score erkennt die Luecke zwischen Dokumentation und Realitaet.
CI-Gate verhindert, dass die Luecke ueber einen Schwellenwert waechst.
Webhook alarmiert das Team, wenn der Drift sich beschleunigt.
Team aktualisiert die Dokumentation (oder fuehrt eine Discovery aus, um sie automatisch zu aktualisieren).
KI-Agent liest das aktualisierte Modell. Die Schleife schliesst sich.

Ohne Schritt 3 ist die Schleife offen. Dokumentation driftet. Agenten stuetzen sich auf veralteten Kontext. Schlechte Entscheidungen haeufen sich.

Der Drift Score schliesst die Schleife.

Erste Schritte

Oeffnen Sie ein beliebiges Projekt in Archyl
Klicken Sie auf das Herzschlag-Symbol in der Kopfzeilen-Toolbar
Klicken Sie auf "Compute Drift Score"
Richten Sie die GitHub Action fuer kontinuierliches Monitoring ein
Konfigurieren Sie einen Slack-Webhook fuer drift.score_degraded-Benachrichtigungen

Ihre Architekturdokumentation spiegelt entweder die Realitaet wider oder nicht. Jetzt haben Sie eine Zahl, die Ihnen sagt, was davon zutrifft.

Architecture Drift Score: Sagt Ihre Dokumentation die Wahrheit? - Archyl Blog