Architektur-Entscheidungsprotokolle

Architecture Decision Records (Architektur-Entscheidungsprotokolle)

Halte Architekturentscheidungen fest, sobald sie während Codierungssitzungen getroffen werden. Anstatt dass Entscheidungen nur in Slack-Threads, PR-Kommentaren oder der Erinnerung von jemandem existieren, erzeugt diese Fertigkeit strukturierte ADR-Dokumente, die zusammen mit dem Code leben.

Wann aktivieren

• Benutzer sagt explizit: „Lass uns diese Entscheidung aufzeichnen“ oder „ADR das“
• Benutzer wählt zwischen bedeutenden Alternativen (Framework, Bibliothek, Muster, 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?“ (bestehende ADRs lesen)
• Während Planungsphasen, wenn architektonische Abwägungen diskutiert werden

ADR-Format

Verwende das schlanke ADR-Format, vorgeschlagen von Michael Nygard, angepasst für KI-gestützte Entwicklung:

# ADR-NNNN: [Entscheidungstitel]

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

## Kontext

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

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

## Entscheidung

Was ist die Änderung, die wir vorschlagen und/oder durchführen?

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

## Alternativen erwogen

### Alternative 1: [Name]
- **Vorteile**: [Nutzen]
- **Nachteile**: [Nachteile]
- **Warum nicht**: [spezifischer Grund für die Ablehnung]

### Alternative 2: [Name]
- **Vorteile**: [Nutzen]
- **Nachteile**: [Nachteile]
- **Warum nicht**: [spezifischer Grund für die Ablehnung]

## Konsequenzen

Was wird durch diese Änderung einfacher oder schwieriger?

### Positiv
- [Vorteil 1]
- [Vorteil 2]

### Negativ
- [Zielkonflikt 1]
- [Zielkonflikt 2]

### Risiken
- [Risiko und Minderung]

Arbeitsablauf

Erfassen eines neuen ADR

Wenn ein Entscheidungsmoment erkannt wird:

1. Initialisieren (nur beim ersten Mal) – falls docs/adr/ nicht existiert, frage den Benutzer um Bestätigung, bevor das Verzeichnis, eine README.md mit dem Index-Tabellenkopf (siehe ADR-Index-Format unten) und eine leere template.md zur manuellen Verwendung erstellt werden. Erstelle keine Dateien ohne explizite Zustimmung.
2. Entscheidung identifizieren – extrahiere die grundlegende architektonische Wahl, die getroffen wird.
3. Kontext sammeln – welches Problem hat dazu geführt? Welche Einschränkungen gibt es?
4. Alternativen dokumentieren – welche anderen Optionen wurden erwogen? Warum wurden sie abgelehnt?
5. Konsequenzen benennen – was sind die Abwägungen? Was wird einfacher/schwieriger?
6. Nummer zuweisen – durchsuche bestehende ADRs in docs/adr/ und erhöhe den Zähler.
7. Bestätigen und schreiben – lege den ADR-Entwurf dem Benutzer zur Überprüfung vor. Schreibe nur nach expliziter Genehmigung in docs/adr/NNNN-entscheidungstitel.md. Wenn der Benutzer ablehnt, verwerfe den Entwurf, ohne Dateien zu schreiben.
8. Index aktualisieren – hänge an docs/adr/README.md an.

Vorhandene ADRs lesen

Wenn ein Benutzer fragt: „Warum haben wir X gewählt?“:

1. Prüfe, ob docs/adr/ existiert – falls nicht, antworte: „In diesem Projekt wurden keine ADRs gefunden. Möchten Sie beginnen, Architekturentscheidungen aufzuzeichnen?“
2. Wenn es existiert, durchsuche den Index docs/adr/README.md nach relevanten Einträgen.
3. Lese die passenden ADR-Dateien und präsentiere die Abschnitte Kontext und Entscheidung.
4. Wenn keine Übereinstimmung gefunden wird, antworte: „Für diese Entscheidung wurde kein ADR gefunden. Möchten Sie 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 Verwendung

ADR-Index-Format

# Architecture Decision Records (Architektur-Entscheidungsprotokolle)

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

Signale zur Entscheidungserkennung

Achte auf diese Muster im Gespräch, die auf eine Architekturentscheidung hindeuten:

Explizite Signale

• „Lass uns mit X gehen“
• „Wir sollten X anstelle von Y verwenden“
• „Der Zielkonflikt ist es wert, weil...“
• „Zeichne dies als ADR auf“

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

• Vergleichen von zwei Frameworks oder Bibliotheken und Erreichen einer Schlussfolgerung
• Treffen einer Datenbankschema-Designentscheidung mit begründeter Begründung
• Wählen zwischen Architekturmustern (Monolith vs. Microservices, REST vs. GraphQL)
• Entscheiden über Authentifizierungs-/Autorisierungsstrategie
• Auswählen der Bereitstellungsinfrastruktur nach Bewertung von Alternativen

Was einen guten ADR ausmacht

Tun

• Sei spezifisch – „Verwende Prisma ORM“, nicht „verwende ein ORM“
• Halte das Warum fest – die Begründung ist wichtiger als das Was
• Schließe abgelehnte Alternativen ein – zukünftige Entwickler müssen wissen, was erwogen wurde
• Formuliere Konsequenzen ehrlich – jede Entscheidung hat Abwägungen
• Halte es kurz – ein ADR sollte in 2 Minuten lesbar sein
• Verwende die Gegenwartsform – „Wir verwenden X“, nicht „Wir werden X verwenden“

Nicht tun

• Triviale Entscheidungen aufzeichnen – Variablennamen oder Formatierungsentscheidungen brauchen keine ADRs
• Aufsätze schreiben – wenn der Kontextabschnitt 10 Zeilen überschreitet, ist er zu lang
• Alternativen weglassen – „wir haben es einfach ausgewählt“ ist keine gültige Begründung
• Nachträglich ohne Kennzeichnung ausfüllen – wenn eine vergangene Entscheidung aufgezeichnet wird, notiere das ursprüngliche Datum
• ADRs veralten lassen – ersetzte Entscheidungen sollten auf ihre Ersetzung 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. Feature entfernt)
• ersetzt: ein neuerer ADR ersetzt diesen (immer auf die Ersetzung verlinken)

Kategorien von Entscheidungen, die es wert sind, aufgezeichnet zu werden

Kategorie	Beispiele
Technologieentscheidungen	Framework, Sprache, Datenbank, Cloud-Anbieter
Architekturmuster	Monolith vs. Microservices, ereignisgesteuert, CQRS
API-Design	REST vs. GraphQL, Versionierungsstrategie, Authentifizierungsmechanismus
Datenmodellierung	Schema-Design, Normalisierungsentscheidungen, Caching-Strategie
Infrastruktur	Bereitstellungsmodell, CI/CD-Pipeline, Monitoring-Stack
Sicherheit	Auth-Strategie, Verschlüsselungsansatz, Geheimnisverwaltung
Testen	Test-Framework, Abdeckungsziele, E2E- vs. Integrations-Balance
Prozess	Branching-Strategie, Review-Prozess, Release-Rhythmus

Integration mit anderen Fertigkeiten

• Planer-Agent: Wenn der Planer Architekturänderungen vorschlägt, schlage die Erstellung eines ADR vor
• Code-Reviewer-Agent: Markiere PRs, die Architekturänderungen ohne entsprechenden ADR einführen