Governance und Drift

← Zurück zur Übersicht

1. Sicherheits- und Berechtigungsmodell

AURA muss beantworten können:

• Wer darf welche Services sehen?
• Welche Repositories sind vertraulich?
• Welche Dokumente enthalten Security-Details?
• Darf ein AI Assistant nur lesen?
• Darf ein AI Assistant Code abrufen?
• Darf ein AI Assistant PRs kommentieren?
• Darf ein AI Assistant Tickets anlegen?
• Darf ein AI Assistant Dokumentationsvorschläge erstellen?

Besonders wichtig ist das bei:

• Security-Dokumentation
• Infrastrukturinformationen
• Kundendaten
• Secrets
• internen Schnittstellen
• produktkritischen Services
• Code-Kontextabruf durch KI

2. Architekturdrift

AURA sollte langfristig Architekturdrift erkennen.

Architekturdrift bedeutet: Der Code verhält sich anders als die dokumentierte Architektur beschreibt.

Beispiele:

• Code importiert einen Service, der nicht als Abhängigkeit dokumentiert ist.
• Ein neues API-Endpoint existiert, aber OpenAPI wurde nicht aktualisiert.
• Ein neues Event wird publiziert, aber AsyncAPI fehlt.
• Deployment nutzt eine neue Datenbank, aber die Architektur-Doku erwähnt sie nicht.
• Ein ADR sagt, dass direkte Calls verboten sind, aber Code führt direkte Calls ein.

AURA kann Drift erkennen durch:

• statische Codeanalyse
• Dependency Scans
• API-Diffing
• Event-Contract-Diffing
• Infrastruktur-Diffing
• Vergleich mit architecture.yaml
• KI-gestützte Analyse
• PR-Diff-Analyse

3. Menschliche Kontrolle

AURA soll KI nutzen, aber nicht die Kontrolle an KI abgeben.

KI darf vorschlagen, zusammenfassen und prüfen. Menschen entscheiden und verantworten.

KI darf helfen bei:

• Zusammenfassungen
• Doku-Entwürfen
• ADR-Entwürfen
• Diagramm-Vorschlägen
• Inkonsistenzsuche
• PR-Kommentaren
• Feature-Impact-Analysen
• Architekturdrift-Erkennung

Menschen bleiben verantwortlich für:

• Architekturentscheidungen
• Freigaben
• Review
• Ownership
• Priorisierung
• Qualitätsbewertung
• Ausnahmen
• Governance

4. AI-generierte Dokumentation

AURA sollte KI-generierte Dokumentation unterstützen, aber nicht unkritisch akzeptieren.

Besser als:

Jedes Repo bekommt eine KI-generierte Dokumentation.

ist:

Jedes Repo bekommt eine normalisierte, versionierte Architektur-Dokumentation, die KI erstellen oder aktualisieren darf, aber die durch Menschen und CI-Regeln reviewt wird.

Qualitätsmerkmale der Dokumentation sind nicht, dass sie KI-generiert ist. Qualitätsmerkmale sind:

• versioniert
• reviewbar
• standardisiert
• verständlich
• maschinenlesbar
• aktuell
• durch Owner verantwortet
• durch CI geprüft
• quellenbasiert

5. Service Graph

AURA sollte langfristig einen Service Graph aufbauen.

Knoten:

Produkte
Systeme
Services
Teams
APIs
Events
Datenbanken
Queues
Jira Epics
ADRs
Repositories
Deployment-Umgebungen

Kanten:

owns
belongs_to
depends_on
provides_api
consumes_api
publishes_event
consumes_event
deployed_to
decided_by
implemented_by
related_to_ticket

Dieser Graph ist für Menschen und KI wertvoll.

Beispiel

team-payments
  owns -> billing-service

billing-service
  belongs_to -> commerce-platform
  depends_on -> user-service
  depends_on -> payment-provider-adapter
  provides_api -> billing-api
  publishes_event -> invoice-created
  documented_by -> docs/architecture/overview.md
  decided_by -> ADR-0002
  changed_by -> PR-847
  related_to_ticket -> PAY-123

6. Policies und Regeln

AURA braucht Regeln, die definieren, wann etwas gültig ist.

Beispiele:

• Jeder produktive Service braucht einen Owner.
• Jeder kritische Service braucht mindestens C1- und C2-Diagramme.
• Jede öffentliche API braucht OpenAPI.
• Jedes Event braucht AsyncAPI oder Event-Dokumentation.
• Jede neue externe Abhängigkeit braucht ein ADR.
• Jede Änderung an Security/Auth braucht Review durch Security-Team.
• Jede Änderung an Datenhaltung braucht Doku-Update.
• Jede kritische Doku muss spätestens alle 90 Tage reviewed werden.

Diese Regeln können schrittweise eingeführt werden.

7. Policy-as-Code

Langfristig können AURA-Regeln als Policy-as-Code gepflegt werden:

rules:
  - id: productive-service-requires-owner
    severity: error
    when:
      lifecycle: production
    require:
      - owner

  - id: critical-service-requires-c4
    severity: error
    when:
      criticality: high
    require:
      - documentation.c4_context
      - documentation.c4_container

  - id: public-api-requires-openapi
    severity: error
    when:
      provides_public_api: true
    require:
      - contracts.openapi

  - id: external-dependency-requires-adr
    severity: warning
    when:
      dependency_added: external
    require:
      - adr

8. Metriken

AURA kann langfristig Qualitätsmetriken liefern:

• Anzahl Services mit validierter Doku
• Anzahl Services ohne Owner
• Anzahl kritischer Services ohne C4-Diagramm
• Anzahl PRs mit architekturrelevanten Änderungen
• Anzahl PRs mit fehlendem Doku-Update
• Durchschnittliches Alter der Doku
• Anzahl ADRs pro Produktbereich
• Anzahl erkannter Drift-Fälle
• Anzahl Feature-Analysen durch AURA

Diese Metriken sollten nicht zur Bestrafung einzelner Entwickler genutzt werden, sondern zur Verbesserung der Systemqualität.

Weiterlesen

• Nächste Seite: Einführung — Phasen, MVP und Rollout
• Dokumentation — Trust Status pro Dokument
• PR Check — wie Policies im PR durchgesetzt werden
• KI und MCP — geprüfter Kontext und Berechtigungen

← Zurück zur Übersicht