AURA

PR Check

Bei jedem Pull Request wird AURA getriggert. AURA analysiert den PR und prüft, ob relevante Architekturinformationen angepasst wurden.

← Zurück zur Übersicht

PR Check

1. Was prüft AURA bei einem Pull Request?

Bei jedem Pull Request wird AURA getriggert. AURA analysiert den PR und prüft, ob relevante Architekturinformationen angepasst wurden.

Der PR Check sollte unter anderem prüfen:

Welche Dateien wurden geändert?
Welche Services sind betroffen?
Gibt es API-Änderungen?
Gibt es neue Abhängigkeiten?
Wurde Infrastruktur geändert?
Wurde Deployment geändert?
Wurde Security/Auth geändert?
Wurde Datenhaltung geändert?
Wurde Eventing/Messaging geändert?
Wurde die Architektur-Doku angepasst?
Wurde ein ADR ergänzt?
Wurden C4-Diagramme aktualisiert?
Wurden Ownership oder Metadaten verändert?

2. Wann ist Doku-Pflicht?

AURA sollte nicht bei jeder kleinen Codeänderung Dokumentation verlangen. Das wäre zu nervig und würde Akzeptanz zerstören.

AURA sollte aber Doku verlangen, wenn architekturrelevante Änderungen erkannt werden:

  • Eine öffentliche API ändert sich.
  • Ein Event oder Topic ändert sich.
  • Eine neue Abhängigkeit wird eingeführt.
  • Eine Abhängigkeit wird entfernt.
  • Ein neuer Service wird integriert.
  • Deployment oder Runtime ändern sich.
  • Security oder Authentifizierung ändern sich.
  • Datenhaltung oder Datenfluss ändern sich.
  • Ein neues technisches Pattern wird eingeführt.
  • Ein bestehendes Architekturprinzip wird verletzt.
  • Ein kritisches Qualitätsziel wird berührt.

Wenn eine solche Änderung erkannt wird, sollte mindestens eines der folgenden Artefakte angepasst werden:

architecture.yaml
C4-Diagramm
ADR
OpenAPI/AsyncAPI
Service-Dokumentation
Deployment-Dokumentation
Security-/Risk-Dokumentation
Quality Goals

3. Verhalten bei fehlender Dokumentation

Wenn AURA erkennt, dass eine architekturrelevante Änderung nicht dokumentiert wurde, gibt es verschiedene Eskalationsstufen:

Weich:
  AURA kommentiert im PR.

Mittel:
  AURA erzeugt eine Warning und benachrichtigt Owner.

Hart:
  AURA blockiert den Merge als Required Check.

Empfohlene Einführung:

Phase 1: Nur Hinweise
Phase 2: Warnungen mit Owner-Benachrichtigung
Phase 3: Harte Gates für kritische Repos, APIs und Architekturänderungen

So kann AURA eingeführt werden, ohne die Teams sofort zu blockieren.

4. Beispiel: AURA PR-Kommentar

Ein AURA-Kommentar in einem PR könnte etwa so aussehen:

## AURA Architecture Check

AURA detected architecture-relevant changes in this PR.

### Detected changes
- New dependency added: `payment-provider-adapter`
- OpenAPI contract changed: `POST /invoices`
- Deployment configuration changed: new environment variable `PAYMENT_TIMEOUT_MS`

### Required documentation updates
- Update `docs/architecture/containers.md`
- Update `docs/api/openapi.yaml`
- Consider adding an ADR for the new payment provider integration

### Status
Warning: Documentation update incomplete.

Owner: team-payments
Related Jira: PAY-123

5. Beispiel-Regeln (Policy-as-Code)

Die PR-Regeln können als Konfigurationsdatei gepflegt werden:

checks:
  - id: docs-updated-for-api-change
    description: API changes require OpenAPI and architecture documentation updates.
    trigger:
      changedFiles:
        - "src/**/controller/**"
        - "src/**/api/**"
    requireOneOf:
      - "docs/api/openapi.yaml"
      - "docs/architecture/**"
    severity: warning

  - id: adr-required-for-new-external-dependency
    description: New external dependencies require an ADR.
    trigger:
      dependencyAdded:
        type: external
    require:
      - "docs/adr/*.md"
    severity: warning

  - id: c4-required-for-critical-service
    description: Critical services require context and container diagrams.
    trigger:
      metadata:
        criticality: high
    require:
      - "docs/architecture/context.*"
      - "docs/architecture/container.*"
    severity: error

6. Commit, PR oder Merge?

AURA sollte nicht jeden einzelnen Commit als zentrale Wahrheit behandeln. Ein Commit kann ein Zwischenzustand sein.

Besser:

Feature Branch:
  Entwickler und KI ändern Code und lokale Doku

Pull Request:
  AURA prüft Code, Tests, Doku, Diagramme, ADRs und Contracts

Merge nach main:
  AURA aktualisiert zentrale Architekturübersicht

Release:
  optional wird ein versionierter Architekturstand eingefroren

Der zentrale AURA-Stand sollte geprüfte Zustände zeigen, nicht beliebige Zwischenstände.

7. Detaillierter Ablauf

1. Entwickler erstellt Jira Ticket oder erhält Feature Request.
2. Entwickler fragt AURA nach betroffenen Systemen und Repositories.
3. AURA analysiert Featurebeschreibung anhand von Architekturkontext.
4. Entwickler oder KI-Agent implementiert Änderung im passenden Repository.
5. Falls nötig, aktualisiert Entwickler oder KI-Agent Doku, ADRs, C4-Diagramme und API-Specs.
6. Pull Request wird geöffnet.
7. AURA PR Check wird getriggert.
8. AURA analysiert Diff, Metadaten und Dokumentationsänderungen.
9. AURA kommentiert fehlende oder inkonsistente Dokumentation.
10. Menschlicher Reviewer prüft Code und AURA-Hinweise.
11. PR wird gemerged.
12. AURA Ingest zieht validierte Artefakte aus main.
13. AURA erzeugt Architecture Snapshot.
14. AURA aktualisiert Webseite, Suchindex, Embeddings und Service Graph.
15. KI-Assistenten können über MCP auf den aktualisierten Kontext zugreifen.

Weiterlesen

← Zurück zur Übersicht

Dokumentation

Ingest und Portal