Dokumentation

Der Aura-Dokumentationsstandard legt fest, welche Markdown-Dateien unter docs/aura liegen, welche Pflicht sind und wie Agenten damit arbeiten.

← Zurück zur Übersicht

Schichten der Doku: Markdown für Menschen, Metadaten für Maschinen, C4 für Strukturen

1. Aura-Dokumentation in Markdown

Die menschliche Dokumentation liegt in Markdown unter docs/aura/. Diese Struktur ist der Vertrag zwischen Repository, Review-Prozess, Portal und KI-Assistenten:

docs/aura/
├── README.md
├── 01-overview/
├── 02-architecture/
├── 03-integrations/
├── 04-product/
├── 05-technical/
├── 06-operations/
└── 07-development/

Diese Dokumente sind zuerst für Menschen gedacht. Gleichzeitig sind sie stabil genug strukturiert, damit AURA sie prüfen, indexieren und als KI-Kontext verwenden kann.

Wichtig: Aura-Dokumente dürfen von KI erstellt oder aktualisiert werden, müssen aber durch Menschen reviewt und durch CI-Regeln validiert werden.

→ Markdown-Vorlagen siehe Vorlagen und Skill. Der passende Skill steht unter Aura Skill zum Download.

2. Überblick und Glossar

01-overview/ beantwortet: Was ist dieses System?

01-overview/
├── system-description.md
├── system-classification.md
├── glossary.md
└── conventions.md

Dieser Bereich enthält Zweck, Stakeholder, Geschäftskontext, Klassifikation, Sprache und Terminologie. Das Glossar ist die Single Source of Truth für Fachbegriffe. Begriffe aus 04-product/ sollten dorthin verlinken, statt Definitionen zu duplizieren.

3. Technische Architektur

02-architecture/ beantwortet: Wie ist es gebaut?

02-architecture/
├── overview.md
├── components.md
├── data-model.md
├── data-model/
│   └── <entity>.md
├── decisions/
│   ├── README.md
│   └── 0001-<slug>.md
└── diagrams/

AURA verwendet hier weiterhin C4 als Denkmodell:

C1: System Context
C2: Container
optional C3: Component

Ein gutes C4-Diagramm beantwortet schnell:

Wo bin ich?
Was gehört dazu?
Was gehört nicht dazu?
Wer spricht mit wem?
Über welche Schnittstelle?
Warum ist das so?

Beispiel: C4 Container-Diagramm eines Services

4. Datenmodell und Product-Doku

Das technische Datenmodell liegt unter 02-architecture/data-model/. Die fachliche Bedeutung derselben Entities gehört nach 04-product/.

02-architecture/data-model/customer.md
04-product/customer-management/entities/customer.md

Zwischen beiden Seiten sind bidirektionale Links Pflicht:

die technische Entity verlinkt auf die fachliche Beschreibung
die fachliche Entity verlinkt zurück auf Schema, Tabelle, Code oder Migration

So bleibt klar getrennt, was aus Code ableitbar ist und was Domänenwissen ist.

5. Integrationen

03-integrations/ beantwortet: Womit redet das System?

03-integrations/
├── README.md
├── upstream/
├── downstream/
└── infrastructure/

Downstream-Dateien beschreiben Systeme, die dieses Repository aufruft. Upstream-Dateien beschreiben Systeme, die dieses Repository aufrufen. Infrastruktur umfasst Datenbanken, Queues, Caches, Object Storage und vergleichbare Laufzeitabhängigkeiten.

Für jede Integration sollten mindestens Zweck, Protokoll, Authentifizierung, Fehlerstrategie, Owner und SLAs dokumentiert werden. Was der Code nicht zeigt, bleibt als AURA-TODO markiert.

6. Product und Technical

04-product/ enthält fachliche Komponenten, Entities, Workflows und Geschäftsregeln. Dieser Bereich darf nicht aus Code halluziniert werden. Der Skill kann Kandidaten vorschlagen, die fachliche Bedeutung muss aber ein Mensch bestätigen.

05-technical/ enthält Cross-Cutting Concerns wie:

authentication.md
authorization.md
audit-logging.md
file-storage.md
event-bus.md
caching.md
i18n.md

Abgrenzung: JWT-Mechanik gehört nach 05-technical/authentication.md. Rollen, Berechtigungen und fachliche Zugriffsregeln gehören nach 04-product/.

7. Operations und Development

06-operations/ dokumentiert Betrieb:

06-operations/
├── deployment.md
├── environments.md
├── observability.md
└── runbooks/

07-development/ dokumentiert Arbeit am Repository:

07-development/
├── setup.md
├── workflows.md
├── testing.md
└── quality-gates.md

Diese Dateien sind besonders agentenfreundlich: Setup-Kommandos, Test-Buckets und Quality Gates lassen sich direkt für Onboarding, PR-Checks und lokale Agentenläufe verwenden.

8. Diagrammquellen statt Screenshots

Diagramme sollten nicht nur als Bilder gespeichert werden. Die Quelle des Diagramms sollte versioniert im Repository liegen, idealerweise direkt in 02-architecture/overview.md, 02-architecture/components.md oder unter 02-architecture/diagrams/.

Mögliche Formate:

Mermaid
PlantUML
Structurizr DSL
C4-PlantUML

Für den Start ist Mermaid attraktiv, weil es einfach in Markdown eingebettet werden kann. Für komplexere Landschaften mit vielen Services kann ein modellbasierter Ansatz besser sein.

Mögliche Stufen:

Einfach:
Markdown + Mermaid

Robuster:
Markdown + Mermaid oder PlantUML + feste Regeln

Architekturmodelliert:
Structurizr DSL / C4-Modell / Service Graph

Empfehlung:

Für einzelne Repo-Diagramme kann Mermaid reichen.
Für organisationsweite Architektur- und Abhängigkeitsmodelle sollte AURA langfristig ein strukturiertes Modell pflegen.
Structurizr DSL oder ein eigener normalisierter Service Graph können dafür sinnvoll sein.

9. ADRs — Architecture Decision Records

C4 zeigt, wie die Architektur aussieht. ADRs erklären, warum sie so ist.

ADRs liegen in der Aura-Struktur unter 02-architecture/decisions/:

docs/aura/02-architecture/decisions/README.md
docs/aura/02-architecture/decisions/0001-use-postgres.md
docs/aura/02-architecture/decisions/0002-introduce-event-driven-billing.md

Ein ADR sollte mindestens enthalten:

Titel
Status
Kontext
Entscheidung
Alternativen
Konsequenzen
Links zu Jira, PRs, Diagrammen und Code

Beispiel-ADR

# ADR-0003: Remove direct dependency to user-service

## Status
Accepted

## Context
The billing-service currently calls user-service synchronously during invoice creation.

## Decision
We will replace the synchronous call with user-profile events.

## Consequences
- billing-service becomes less coupled to user-service
- eventual consistency must be handled
- additional event processing is required

## Related
- Jira: PAY-123
- PR: #847
- Services: billing-service, user-service

→ ADR-Template siehe Vorlagen und Skill.

10. Konfidenz, TODOs und Trust

Aura-Dokumente dürfen Lücken explizit zeigen. Der Skill nutzt dafür Konfidenz- und TODO-Marker:

<!-- confidence: high — abgeleitet aus package.json und nuxt.config.ts -->
<!-- confidence: inferred — aus Tabellenname und Beziehungen vermutet -->
<!-- AURA-TODO: Wer ist fachlicher Owner dieser Integration? -->

Jede Service-Seite und jedes Dokument in AURA sollte zusätzlich einen sichtbaren Vertrauensstatus haben:

validated
outdated
missing owner
missing C4
missing ADR
documentation drift detected
AI-generated, not human-approved
last reviewed over threshold
source unavailable

Beispiel:

documentation_status: validated
last_human_review: 2026-05-01
last_ingested: 2026-05-09
source_commit: a81f3c2
ai_generated: true
human_approved: true
drift_detected: false

Das ist wichtig, damit Menschen und KI der Dokumentation nicht blind vertrauen.

Weiterlesen

Nächste Seite: PR Check — wie AURA Doku-Pflicht durchsetzt
Aura Skill — Research-First-Skill herunterladen
Vorlagen und Skill — vollständige Aura-Templates
Governance und Drift — Drift-Erkennung und Trust-Bewertung

← Zurück zur Übersicht

Repository-Standard

PR Check