Architektur-Entscheidungsprotokolle (ADR)

Was macht Architektur-Entscheidungsprotokolle (ADR)?

Erfasse Architekturentscheidungen während der Codierung live. Statt dass Entscheidungen nur in Slack-Threads, PR-Kommentaren oder dem Gedächtnis einer Person existieren, erstellt dieses Skill strukturierte ADR-Dokumente, die neben dem Code leben.

Wann aktivieren

• Benutzer sagt explizit „lass uns diese Entscheidung aufzeichnen" oder „ADR dies"
• Benutzer wählt zwischen signifikanten Alternativen (Framework, Bibliothek, Architekturmuster, Datenbank, API-Design)
• Benutzer sagt „wir haben uns entschieden..." oder „der Grund, warum wir X statt Y machen, ist..."
• Benutzer fragt „warum haben wir X gewählt?" (existierende ADRs lesen)
• Während Planungsphasen, wenn architektonische Kompromisse diskutiert werden

ADR-Format

Verwende das von Michael Nygard vorgeschlagene und für KI-gestützte Entwicklung adaptierte Lightweight-ADR-Format:

# ADR-NNNN: [Entscheidungstitel]

**Datum**: YYYY-MM-DD
**Status**: vorgeschlagen | akzeptiert | veraltet | ersetzt durch ADR-NNNN
**Entscheider**: [wer war beteiligt]

## Kontext

Was ist das Problem, das wir sehen und das diese Entscheidung oder Änderung motiviert?

[2-5 Sätze, die die Situation, Rahmenbedingungen und die wirkenden Kräfte beschreiben]

## Entscheidung

Was ist die Änderung, die wir vorschlagen und/oder umsetzen?

[1-3 Sätze, die die Entscheidung klar darlegen]

## Alternativen

### Alternative 1: [Name]
- **Vorteile**: [Nutzen]
- **Nachteile**: [Nachteile]
- **Warum nicht**: [spezifischer Grund, warum abgelehnt]

### Alternative 2: [Name]
- **Vorteile**: [Nutzen]
- **Nachteile**: [Nachteile]
- **Warum nicht**: [spezifischer Grund, warum abgelehnt]

## Konsequenzen

Was wird durch diese Änderung einfacher oder schwieriger?

### Positive
- [Vorteil 1]
- [Vorteil 2]

### Negative
- [Kompromiss 1]
- [Kompromiss 2]

### Risiken
- [Risiko und Gegenmaßnahme]

Arbeitsablauf

Erfassen eines neuen ADR

Wenn ein Entscheidungsmoment erkannt wird:

1. Initialisieren (nur beim ersten Mal) – falls docs/adr/ nicht existiert, den Benutzer um Bestätigung bitten, bevor das Verzeichnis, eine README.md mit der Index-Tabellenkopfzeile (siehe ADR-Index-Format unten) und eine leere template.md für die manuelle Nutzung erstellt werden. Keine Dateien ohne explizite Zustimmung erstellen.
2. Entscheidung identifizieren – die Kernarchitekturentscheidung extrahieren
3. Kontext sammeln – welches Problem hat dazu geführt? Welche Rahmenbedingungen gibt es?
4. Alternativen dokumentieren – welche anderen Optionen wurden in Betracht gezogen? Warum wurden sie abgelehnt?
5. Konsequenzen festhalten – was sind die Kompromisse? Was wird einfacher/schwieriger?
6. Nummer zuweisen – existierende ADRs in docs/adr/ scannen und hochzählen
7. Bestätigen und schreiben – den ADR-Entwurf dem Benutzer zur Überprüfung vorlegen. Erst nach expliziter Genehmigung in docs/adr/NNNN-entscheidungstitel.md schreiben. Lehnt der Benutzer ab, den Entwurf verwerfen, ohne Dateien zu schreiben.
8. Index aktualisieren – an docs/adr/README.md anhängen

Lesen existierender ADRs

Wenn ein Benutzer fragt „warum haben wir X gewählt?":

1. Prüfe, ob docs/adr/ existiert – falls nicht, antworte: „Keine ADRs in diesem Projekt gefunden. Möchtest du beginnen, Architekturentscheidungen aufzuzeichnen?"
2. Wenn es existiert, durchsuche den Index docs/adr/README.md nach relevanten Einträgen
3. Lese passende ADR-Dateien und präsentiere die Abschnitte Kontext und Entscheidung
4. Wenn kein Treffer gefunden wird, antworte: „Kein ADR zu dieser Entscheidung gefunden. Möchtest du jetzt einen aufzeichnen?"

ADR-Verzeichnisstruktur

docs/
└── adr/
    ├── README.md              ← Index aller ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← leere Vorlage zur manuellen Nutzung

ADR-Index-Format

# Architektur-Entscheidungsprotokolle

| ADR | Titel | Status | Datum |
|-----|-------|--------|-------|
| [0001](0001-use-nextjs.md) | Next.js als Frontend-Framework verwenden | akzeptiert | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL statt MongoDB für primäre Datenhaltung | akzeptiert | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST-API statt GraphQL | akzeptiert | 2026-02-01 |

Signale zur Erkennung von Entscheidungen

Achte auf folgende Muster in Gesprächen, die auf eine Architekturentscheidung hindeuten:

Explizite Signale

• „Lass uns X nehmen"
• „Wir sollten X statt Y verwenden"
• „Der Kompromiss ist es wert, weil..."
• „Zeichne dies als ADR auf"

Implizite Signale (schlage die Aufzeichnung eines ADR vor – nicht ohne Benutzerbestätigung automatisch erstellen)

• Vergleich zweier Frameworks oder Bibliotheken mit einer Schlussfolgerung
• Datenbankschema-Entwurfsentscheidung mit genannter Begründung
• Wahl zwischen Architekturmustern (Monolith vs. Microservices, REST vs. GraphQL)
• Entscheidung über Authentifizierungs-/Autorisierungsstrategie
• Auswahl der Deployment-Infrastruktur nach Bewertung von Alternativen

Was einen guten ADR ausmacht

Gute Praxis

• Sei konkret – „Prisma ORM verwenden", nicht „ein ORM verwenden"
• Halte das Warum fest – die Begründung ist wichtiger als das Was
• Abgelehnte Alternativen einbeziehen – zukünftige Entwickler müssen wissen, was in Betracht gezogen wurde
• Konsequenzen ehrlich darlegen – jede Entscheidung hat Kompromisse
• Kurz halten – ein ADR sollte in 2 Minuten lesbar sein
• Gegenwartsform verwenden – „Wir verwenden X", nicht „Wir werden X verwenden"

Vermeiden

• Triviale Entscheidungen aufzeichnen – Variablenbenennung oder Formatierungswahl benötigen keine ADRs
• Aufsätze schreiben – wenn der Kontextabschnitt 10 Zeilen überschreitet, ist er zu lang
• Alternativen weglassen – „wir haben es einfach gewählt" ist keine gültige Begründung
• Nachträglich erfassen ohne Kennzeichnung – wenn du eine vergangene Entscheidung aufzeichnest, notiere das ursprüngliche Datum
• ADRs veralten lassen – ersetzte Entscheidungen sollten auf die Ablösung verweisen

ADR-Lebenszyklus

vorgeschlagen → akzeptiert → [veraltet | ersetzt durch ADR-NNNN]

• vorgeschlagen: Entscheidung wird diskutiert, noch nicht umgesetzt
• akzeptiert: Entscheidung ist in Kraft und wird befolgt
• veraltet: Entscheidung ist nicht mehr relevant (z. B. Funktion entfernt)
• ersetzt: Ein neuerer ADR ersetzt diesen (immer auf den Ersatz verlinken)

Entscheidungskategorien, die es wert sind, aufgezeichnet zu werden

Kategorie	Beispiele
Technologieentscheidungen	Framework, Sprache, Datenbank, Cloud-Anbieter
Architekturmuster	Monolith vs. Microservices, Event-Driven, CQRS
API-Design	REST vs. GraphQL, Versionierungsstrategie, Auth-Mechanismus
Datenmodellierung	Schema-Design, Normalisierungsentscheidungen, Caching-Strategie
Infrastruktur	Deployment-Modell, CI/CD-Pipeline, Monitoring-Stack
Sicherheit	Auth-Strategie, Verschlüsselungsansatz, Secret-Management
Testen	Test-Framework, Coverage-Ziele, E2E-vs.-Integration-Ausgleich
Prozess	Branching-Strategie, Review-Prozess, Release-Zyklus

Integration mit anderen Skills

• Planer-Agent: Wenn der Planer Architekturänderungen vorschlägt, empfehle die Erstellung eines ADR
• Code-Reviewer-Agent: Markiere PRs, die architektonische Änderungen ohne korrespondierenden ADR einführen