Repository-Standard
Repository-Standard
1. Repository als Source of Truth
Jedes relevante Projekt oder Repository enthält eine normalisierte technische Dokumentation unter docs/aura/. Diese Dokumentation ist nicht Beiwerk, sondern Teil des Produkts: versioniert, reviewbar und gemeinsam mit dem Code änderbar.
Sie beantwortet mindestens:
- Was ist dieses System?
- Wie ist es technisch gebaut?
- Mit welchen Systemen spricht es?
- Welche fachlichen Komponenten und Begriffe sind wichtig?
- Welche Cross-Cutting Concerns gibt es?
- Wie wird es betrieben?
- Wie arbeitet ein Team daran?
- Welche Entscheidungen, Unsicherheiten und offenen Lücken sind dokumentiert?
Die zentrale AURA-Webseite ist daraus nur das Read Model. Die primäre Wahrheit bleibt im Repository.
2. Verbindliche Aura-Struktur
Die Dokumentation liegt in sieben nummerierten Bereichen. Die Nummern sind verbindlich, weil sie die Lesereihenfolge für Menschen und Agenten kodieren.
docs/aura/
├── README.md
├── 01-overview/
│ ├── system-description.md
│ ├── system-classification.md
│ ├── glossary.md
│ └── conventions.md
├── 02-architecture/
│ ├── overview.md
│ ├── components.md
│ ├── data-model.md
│ ├── data-model/
│ └── decisions/
├── 03-integrations/
├── 04-product/
├── 05-technical/
├── 06-operations/
└── 07-development/
docs/aura/README.md ist die Navigationskarte. Die Detailinformationen leben genau einmal an ihrem kanonischen Ort und werden von anderen Dokumenten verlinkt.
3. Pflichtbereiche
| Bereich | Zweck | Pflicht |
|---|---|---|
README.md | Einstieg und Navigationskarte | immer |
01-overview/ | Systemzweck, Klassifikation, Glossar, Konventionen | immer |
02-architecture/ | technische Architektur, Komponenten, Datenmodell, ADRs | immer |
03-integrations/ | Upstream, Downstream, Infrastruktur | falls externe Abhängigkeiten existieren |
04-product/ | fachliche Komponenten, Entities, Workflows | für domänengetragene Systeme |
05-technical/ | Cross-Cutting Concerns wie Auth, Logging, Caching | immer |
06-operations/ | Deployment, Environments, Observability, Runbooks | für betriebene Systeme |
07-development/ | Setup, Workflows, Testing, Quality Gates | immer |
Damit ist der frühere lose Mix aus docs/architecture/, docs/adr/, docs/quality/ und docs/glossary/ abgelöst. Diese Inhalte bleiben wichtig, bekommen aber feste Orte innerhalb von docs/aura/.
4. Research-First statt leeres Interview
Der Aura-Skill legt Dokumentation nicht durch ein kaltes Frageninterview an. Er folgt einem Research-First-Prozess:
Discover
-> vorhandene Doku, Stack, Repo-Typ und Abhängigkeiten erkennen
Parallel Research
-> Architektur, Datenmodell, Integrationen, Technik, Betrieb und Entwicklung untersuchen
Synthesis
-> Konflikte, Lücken und TODOs konsolidieren
Targeted Interview
-> nur noch die Fragen stellen, die Code und Konfiguration nicht beantworten können
Refinement
-> bestätigte Antworten einarbeiten, Product-Doku und Glossar vervollständigen
Das Ziel ist eine hohe Vorbefüllung: Technik wird aus Code und Konfiguration abgeleitet, Domänenwissen wird bewusst beim Menschen bestätigt.
5. Konfidenz und Lücken
Jede nicht-triviale Aussage braucht eine nachvollziehbare Herkunft. Der Skill unterscheidet:
<!-- confidence: high — direkt aus Migration oder Konfiguration abgeleitet -->
<!-- confidence: inferred — aus Struktur oder Naming plausibel, aber nicht bestätigt -->
<!-- AURA-TODO: Welche Retry-Strategie gilt bei 5xx vom Downstream? -->
Diese Marker sind kein Makel, sondern ein Sicherheitsmechanismus. AURA darf technische Wahrheit aus Code ableiten, aber fachliche Bedeutung, Geschäftsregeln und Entscheidungsgründe nicht erfinden.
6. Ownership
Jede Dokumentation braucht klare Ownership. AURA sollte pro Service mindestens wissen:
owner: team-payments
reviewers:
- team-payments
- architecture-board
- platform-team
criticality: high
lifecycle: production
Ownership ist wichtig für:
- Benachrichtigungen
- Reviews
- Eskalationen
- Veraltete Dokumentation
- Architekturentscheidungen
- Verantwortlichkeit bei kritischen Services
Ohne Ownership wird AURA schnell zu einem passiven Informationssystem ohne Verbindlichkeit.
7. Jira-Integration als First-Class-Kontext
AURA sollte Jira als First-Class-Kontext behandeln und folgende Verbindungen herstellen:
Jira Epic / Story / Task
-> Pull Request
-> Commit
-> Architekturänderung
-> ADR
-> betroffene Services
-> zentrale Architekturansicht
Dadurch werden Fragen möglich wie:
- Welche Services sind durch dieses Epic betroffen?
- Welche Architekturentscheidungen wurden für dieses Feature getroffen?
- Welche PRs haben die Architektur verändert?
- Welche Risiken hängen noch an diesem Jira-Ticket?
- Welche Teams müssen für dieses Feature eingebunden werden?
AURA kann dadurch schon bei der Ticket-Erstellung helfen.
8. Repo-Typen
Die Aura-Struktur ist stabil, aber die Pflichtintensität kann je nach Repository-Typ variieren:
- Service-Repository — produktiver Service mit APIs/Events, hohe Doku-Pflicht
- Library-Repository — gemeinsam genutzte Library, leichter Doku-Standard
- Frontend-Repository — UI-Anwendung, Fokus auf Backend-Abhängigkeiten und APIs
- Infrastruktur-Repository — IaC, Fokus auf Deployment- und Security-Doku
Die sieben Top-Level-Bereiche bleiben gleich. Welche Unterdateien verpflichtend sind, hängt von Laufzeit, Domäne, Integrationen und Kritikalität ab.
Weiterlesen
- Nächste Seite: Dokumentation — vollständige
docs/aura/-Struktur - Aura Skill — Research-First-Skill herunterladen
- Vorlagen und Skill — Templates und CLI-Idee für Aura-Dokumente
- PR Check — wie AURA den Standard prüft