Repository-Standard
Repository-Standard
1. Repository als Source of Truth
Jedes relevante Projekt oder Repository enthält eine normalisierte technische Dokumentation. Diese Dokumentation ist nicht optional. Sie ist Teil des Produkts.
Sie beantwortet mindestens folgende Fragen:
- Was ist dieses Repository?
- Welches System oder Produkt betrifft es?
- Wem gehört es?
- Welche Verantwortung hat es?
- Welche Schnittstellen bietet es?
- Welche externen und internen Abhängigkeiten gibt es?
- Welche Architekturentscheidungen gelten?
- Welche C4-Diagramme beschreiben es?
- Welche Qualitätsziele gelten?
- Welche bekannten Risiken oder technischen Schulden existieren?
- Welche Jira-Epics, Features oder Produktbereiche hängen damit zusammen?
2. Beispielhafte Repo-Struktur
Die genaue Struktur muss noch definiert werden. Eine mögliche Zielstruktur:
/docs
/architecture
overview.md
context.md
containers.md
components.md
runtime.md
deployment.md
/adr
0001-use-event-driven-architecture.md
0002-split-billing-service.md
/quality
quality-goals.md
known-risks.md
technical-debt.md
/api
openapi.yaml
asyncapi.yaml
/glossary
glossary.md
architecture.yaml
catalog-info.yaml
mkdocs.yml
README.md
Diese Struktur trennt menschliche Dokumentation von maschinenlesbaren Metadaten.
3. Maschinenlesbare Metadaten
Zusätzlich zur Markdown-Dokumentation braucht jedes Repository maschinenlesbare Metadaten, damit AURA nicht raten muss, was ein Repository ist.
Beispiel:
service:
name: billing-service
owner: team-payments
product: commerce-platform
domain: payments
lifecycle: production
criticality: high
repository:
url: https://git.example.com/commerce/billing-service
default_branch: main
relationships:
depends_on:
- user-service
- payment-provider-adapter
provides:
- billing-api
- invoice-events
contracts:
openapi: docs/api/openapi.yaml
asyncapi: docs/api/asyncapi.yaml
documentation:
overview: docs/architecture/overview.md
c4_context: docs/architecture/context.md
c4_container: docs/architecture/containers.md
adr_folder: docs/adr
quality_goals: docs/quality/quality-goals.md
known_risks: docs/quality/known-risks.md
jira:
project_key: PAY
related_epics:
- PAY-123
- PAY-456
→ Vollständige architecture.yaml-Vorlage in den Vorlagen.
4. 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.
5. 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.
6. Repo-Typen
Für AURA muss noch definiert werden, welche Repository-Typen unterschieden werden, weil ihre Dokumentationsanforderungen unterschiedlich sind:
- 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
Welche Dateien pro Repo-Typ verpflichtend sind, ist eine offene Entscheidung.
Weiterlesen
- Nächste Seite: Dokumentation — Markdown-Templates, C4, ADRs, Qualität
- Vorlagen und CLI — vollständige
architecture.yaml-Vorlage - PR Check — wie AURA den Standard prüft