Vorlagen und Skill

Diese Seite sammelt die wichtigsten Aura-Templates, den Research-First-Workflow und CLI-Ideen für den praktischen Start.

← Zurück zur Übersicht

Vorlagen und Skill

Übersicht der AURA-Vorlagen: architecture.yaml, Markdown-Templates, ADRs

Diese Seite sammelt die wichtigsten Vorlagen für den praktischen Start mit Aura-Dokumentation. Der vollständige Skill inklusive Research-Protokoll, Interview-Protokoll und Templates steht unter Aura Skill zum Download.

1. `docs/aura/README.md`

# Documentation — {System Name}

**Aura Version:** 1.0  
**System:** {Eine-Zeile-Beschreibung}

## Navigation

| Bereich | Zweck |
|---------|-------|
| [01-overview](./01-overview/) | Was ist dieses System? |
| [02-architecture](./02-architecture/) | Wie ist es gebaut? |
| [03-integrations](./03-integrations/) | Womit redet das System? |
| [04-product](./04-product/) | Fachliche Komponenten |
| [05-technical](./05-technical/) | Technische Komponenten |
| [06-operations](./06-operations/) | Wie läuft es? |
| [07-development](./07-development/) | Wie arbeite ich daran? |

## Einstieg

Neu hier? Starte mit [01-overview/system-description.md](./01-overview/system-description.md).

2. `01-overview/system-description.md`

---
status: draft
aura_version: 1.0
---

# System Description

## Zweck

{Ein bis drei Sätze: Wofür existiert dieses System? Welches Problem löst es?}

## Hauptstakeholder

- {Persona 1}: {Was sie tun}
- {Persona 2}: {Was sie tun}

## Geschäftskontext

{Warum existiert das System? Welcher Geschäftsbereich?}

## Out of Scope

Was dieses System bewusst NICHT tut:

- {Abgrenzung 1}
- {Abgrenzung 2}

3. `02-architecture/overview.md`

# Architecture Overview

## System Context (C4 Level 1)

```mermaid
{System Context Diagram}
```

## Hauptprinzipien

1. {Prinzip 1}
2. {Prinzip 2}

## Wichtige Entscheidungen

Siehe [decisions/](./decisions/) für ADRs.

4. `02-architecture/data-model.md`

# Data Model

## ER-Diagramm

```mermaid
erDiagram
  {Diagramm}
```

## Entities (Index)

| Entity | Schema-Detail | Fachliche Beschreibung |
|--------|---------------|------------------------|
| {Entity1} | [data-model/{entity1}.md](./data-model/{entity1}.md) | [04-product/.../{entity1}.md](../04-product/.../{entity1}.md) |

## Datenbank-Konventionen

- Primary Keys: {z. B. UUIDv7}
- Timestamps: {z. B. created_at, updated_at, deleted_at}
- Soft Deletes: {ja/nein, wo}

5. ADR-Template

# ADR-{NNNN}: {Titel}

**Status:** {Proposed | Accepted | Deprecated | Superseded by ADR-NNNN}  
**Datum:** {YYYY-MM-DD}  
**Entscheider:** {Personen oder Rollen}

## Kontext

{Welches Problem stand zur Entscheidung? Was war der Druck?}

## Entscheidung

{Was wurde entschieden? Aktiv formuliert: „Wir verwenden X."}

## Alternativen

### Option A: {Name}
- Vorteile: {…}
- Nachteile: {…}

### Option B: {Name}
- Vorteile: {…}
- Nachteile: {…}

## Konsequenzen

**Positiv:**
- {…}

**Negativ:**
- {…}

**Neutral:**
- {…}

6. Integration-Template

# Integration: {System Name}

**Richtung:** {Upstream | Downstream}  
**Protokoll:** {REST | gRPC | AMQP | Webhook | ...}  
**Owner (extern):** {Team/Kontakt}

## Zweck der Integration

{Warum reden die beiden Systeme miteinander?}

## Endpunkte / Topics

| Pfad/Topic | Methode | Zweck |
|------------|---------|-------|
| {…} | {…} | {…} |

## Authentifizierung

{Wie wird authentifiziert?}

## Fehler-/Retry-Strategie

<!-- AURA-TODO: Welche Retry-Strategie gilt bei Fehlern? -->

## SLAs / Erwartungen

- Latenz: {…}
- Verfügbarkeit: {…}
- Rate Limits: {…}

7. Product-Entity-Template

# {Entity Name}

**Glossar:** [{Begriff}](../../../01-overview/glossary.md#{anker})  
**Schema:** [02-architecture/data-model/{entity}.md](../../../02-architecture/data-model/{entity}.md)  
**Code:** `{Pfad zur Klasse}`

## Fachliche Bedeutung

{Was repräsentiert diese Entity in der Domäne?}

## Lebenszyklus

{Wie entsteht eine Instanz? Welche Zustände durchläuft sie? Wie endet sie?}

## Invarianten

- {Was muss IMMER gelten?}
- {Was darf NIE eintreten?}

## Geschäftsregeln

1. {Regel}
2. {Regel}

8. Research-First-Konfidenzmarker

Der Skill annotiert Entwürfe sichtbar:

<!-- confidence: high — abgeleitet aus migration 2024_03_15_create_journal_entries -->
| `id` | `uuid` | PK, NOT NULL | Primary Key |

<!-- confidence: inferred — aus Tabellenname und Beziehungen vermutet -->
**Aggregat-Root:** Vermutlich `JournalEntry`, da andere Tabellen darauf referenzieren

<!-- AURA-TODO: Warum wurde UUID statt BIGSERIAL gewählt? -->

Diese Marker bleiben so lange im Dokument, bis ein Mensch sie bestätigt oder die Lücke bewusst offen lässt.

9. `architecture.yaml`

architecture.yaml kann ergänzend genutzt werden, um repo-übergreifende Metadaten maschinenlesbar bereitzustellen. Die menschliche Struktur bleibt docs/aura/.

apiVersion: aura/v1
kind: Service
metadata:
  name: billing-service
  description: Handles invoice creation and billing status updates.
  owner: team-payments
  product: commerce-platform
  domain: payments
  lifecycle: production
  criticality: high

repository:
  provider: github
  url: https://github.example.com/commerce/billing-service
  defaultBranch: main

jira:
  projectKey: PAY
  component: Billing

runtime:
  type: service
  language: java
  framework: spring-boot
  deployment: kubernetes

relationships:
  dependsOn:
    - user-service
    - payment-provider-adapter
  providesApis:
    - billing-api
  publishesEvents:
    - invoice-created
  consumesEvents:
    - user-profile-updated

contracts:
  openapi: docs/aura/03-integrations/downstream/billing-api.openapi.yaml
  asyncapi: docs/aura/03-integrations/downstream/invoice-events.asyncapi.yaml

documentation:
  root: docs/aura
  overview: docs/aura/01-overview/system-description.md
  architecture: docs/aura/02-architecture/overview.md
  components: docs/aura/02-architecture/components.md
  adrFolder: docs/aura/02-architecture/decisions
  operations: docs/aura/06-operations/deployment.md

diagrams:
  c4Context: docs/aura/02-architecture/diagrams/context.mmd
  c4Container: docs/aura/02-architecture/diagrams/container.mmd

review:
  requiredReviewers:
    - team-payments
    - architecture-board
  reviewIntervalDays: 90

10. PR-Check-Regeln

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

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

  - id: c4-required-for-critical-service
    description: Critical services require architecture overview and components.
    trigger:
      metadata:
        criticality: high
    require:
      - "docs/aura/02-architecture/overview.md"
      - "docs/aura/02-architecture/components.md"
    severity: error

11. AURA CLI

Langfristig könnte AURA eine CLI anbieten, die denselben Standard wie der Skill automatisiert.

Initialisierung

aura init docs

Erzeugt docs/aura/ mit allen sieben Top-Level-Bereichen, Pflichtdateien und optionaler architecture.yaml.

Lokale Validierung

aura validate

Prüft lokale Dokumentation.

PR-Check lokal

aura check-pr --base main --head feature-branch

Führt PR-Check lokal oder in CI aus.

Snapshot erzeugen

aura ingest --repo payment-service --commit a81f3c2

Erzeugt Snapshot.

KI-Frage an AURA

aura ask "Which services are affected by invoice changes?"

Fragt AURA-Kontext ab.

12. Service-Snapshot (Beispiel)

So sieht ein generierter Snapshot im AURA-Repository aus:

repo: payment-service
repository_url: https://git.example.com/commerce/payment-service
branch: main
commit: a81f3c2
pr: 847
owner: team-payments
product: commerce-platform
documentation_status: validated
last_ingested: 2026-05-09T14:30:00Z
source_paths:
  - docs/aura/README.md
  - docs/aura/01-overview/system-description.md
  - docs/aura/02-architecture/overview.md
  - docs/aura/02-architecture/components.md
  - docs/aura/02-architecture/decisions/
  - docs/aura/03-integrations/
  - architecture.yaml

Weiterlesen

Nächste Seite: Zusammenfassung — Kernaussagen kompakt
Repository-Standard — wo diese Vorlagen zum Einsatz kommen
Dokumentation — Erläuterung der Markdown-Struktur
Aura Skill — Skill herunterladen und Workflow lesen
PR Check — wie die PR-Regeln durchgesetzt werden

← Zurück zur Übersicht

Abgrenzung und Risiken

Aura Skill