Architecture Decision Records (Architektur-Entscheidungsprotokolle)
Erfasse Architekturentscheidungen, während sie in Codierungssitzungen getroffen werden. Anstatt dass Entscheidungen nur in Slack-Threads, PR-Kommentaren oder in der Erinnerung einer Person leben, produziert dieses Skill strukturierte ADR-Dokumente, die direkt im Code liegen.
Wann zu aktivieren
- Benutzer sagt explizit "lass uns diese Entscheidung festhalten" 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?" (vorhandene ADRs lesen)
- Während Planungsphasen, wenn architektonische Abwägungen diskutiert werden
ADR-Format
Verwende das von Michael Nygard vorgeschlagene leichte ADR-Format, angepasst für KI-gestützte Entwicklung:
# ADR-NNNN: [Entscheidungstitel]
**Datum**: JJJJ-MM-TT
**Status**: vorgeschlagen | akzeptiert | veraltet | ersetzt durch ADR-NNNN
**Entscheider**: [wer beteiligt war]
## Kontext
Was ist das Problem, das diese Entscheidung oder Änderung motiviert?
[2-5 Sätze, die die Situation, Randbedingungen und Kräfte beschreiben]
## Entscheidung
Was ist die Änderung, die wir vorschlagen und/oder durchführen?
[1-3 Sätze, die die Entscheidung klar darlegen]
## Alternativen in Betracht gezogen
### 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 leichter oder schwieriger?
### Positive
- [Nutzen 1]
- [Nutzen 2]
### Negative
- [Kompromiss 1]
- [Kompromiss 2]
### Risiken
- [Risiko und Minderung]
Arbeitsablauf
Erfassen einer neuen ADR
Wenn ein Entscheidungsmoment erkannt wird:
- Initialisieren (nur beim ersten Mal) — falls
docs/adr/nicht existiert, den Benutzer um Bestätigung bitten, bevor das Verzeichnis, eineREADME.mdmit dem Index-Tabellenkopf (siehe ADR-Index-Format unten) und eine leeretemplate.mdfür die manuelle Nutzung erstellt wird. Keine Dateien ohne explizite Zustimmung erstellen. - Entscheidung identifizieren — die Kern-Architekturentscheidung extrahieren
- Kontext sammeln — welches Problem hat dazu geführt? Welche Randbedingungen gibt es?
- Alternativen dokumentieren — welche anderen Optionen wurden in Betracht gezogen? Warum wurden sie abgelehnt?
- Konsequenzen angeben — was sind die Abwägungen? Was wird einfacher/schwieriger?
- Nummer zuweisen — vorhandene ADRs in
docs/adr/scannen und erhöhen - Bestätigen und schreiben — den ADR-Entwurf dem Benutzer zur Überprüfung vorlegen. Nur nach expliziter Genehmigung in
docs/adr/NNNN-entscheidungstitel.mdschreiben. Falls der Benutzer ablehnt, den Entwurf verwerfen, ohne Dateien zu schreiben. - Index aktualisieren — an
docs/adr/README.mdanhängen
Vorhandene ADRs lesen
Wenn ein Benutzer fragt "warum haben wir X gewählt?":
- Prüfen, ob
docs/adr/existiert — falls nicht, antworten: "In diesem Projekt wurden keine ADRs gefunden. Möchten Sie beginnen, Architekturentscheidungen zu dokumentieren?" - Falls ja, den Index
docs/adr/README.mdnach relevanten Einträgen durchsuchen - Passende ADR-Dateien lesen und die Abschnitte Kontext und Entscheidung präsentieren
- Falls keine Übereinstimmung gefunden wird, antworten: "Für diese Entscheidung wurde kein ADR gefunden. Möchten Sie jetzt einen aufnehmen?"
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 für manuelle Nutzung
ADR-Index-Format
# Architecture Decision Records
| 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 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 in der Konversation auf folgende Muster, die auf eine Architekturentscheidung hindeuten:
Explizite Signale
- "Lass uns mit X gehen"
- "Wir sollten X statt Y verwenden"
- "Der Kompromiss lohnt sich, weil..."
- "Halte das als ADR fest"
Implizite Signale (schlage vor, eine ADR aufzuzeichnen — erstelle keine automatisch ohne Benutzerbestätigung)
- Vergleich zweier Frameworks oder Bibliotheken mit Schlussfolgerung
- Treffen einer Datenbankschema-Designentscheidung mit angegebener Begründung
- Wahl zwischen Architekturmustern (Monolith vs. Microservices, REST vs. GraphQL)
- Entscheidung über Authentifizierungs-/Autorisierungsstrategie
- Auswahl der Bereitstellungsinfrastruktur nach Bewertung von Alternativen
Was eine gute ADR ausmacht
Mach
- Sei spezifisch — "Prisma ORM verwenden" nicht "ein ORM verwenden"
- Halte das Warum fest — die Begründung ist wichtiger als das Was
- Schließe abgelehnte Alternativen ein — zukünftige Entwickler müssen wissen, was in Betracht gezogen wurde
- Formuliere Konsequenzen ehrlich — jede Entscheidung hat Abwägungen
- Halte es kurz — eine ADR sollte in 2 Minuten lesbar sein
- Verwende die Gegenwart — "Wir verwenden X" nicht "Wir werden X verwenden"
Mach nicht
- Halte triviale Entscheidungen nicht fest — Variablenbenennung oder Formatierungsentscheidungen brauchen keine ADRs
- Schreibe keine Aufsätze — wenn der Kontextabschnitt mehr als 10 Zeilen überschreitet, ist er zu lang
- Lasse Alternativen nicht aus — "wir haben es einfach so gewählt" ist keine gültige Begründung
- Fülle nicht nach, ohne es zu kennzeichnen — wenn eine vergangene Entscheidung festgehalten wird, notiere das ursprüngliche Datum
- Lasse ADRs nicht veralten — überholte Entscheidungen sollten auf ihren Ersatz verweisen
ADR-Lebenszyklus
vorgeschlagen → akzeptiert → [veraltet | ersetzt durch ADR-NNNN]
- vorgeschlagen: Entscheidung wird diskutiert, noch nicht festgelegt
- akzeptiert: Entscheidung ist in Kraft und wird befolgt
- veraltet: Entscheidung ist nicht mehr relevant (z.B. Funktion entfernt)
- ersetzt: eine neuere ADR ersetzt diese (immer auf den Ersatz verlinken)
Kategorien von dokumentationswürdigen Entscheidungen
| Kategorie | Beispiele |
|---|---|
| Technologieentscheidungen | Framework, Sprache, Datenbank, Cloud-Provider |
| Architekturmuster | Monolith vs. Microservices, ereignisgesteuert, CQRS |
| API-Design | REST vs. GraphQL, Versionierungsstrategie, Auth-Mechanismus |
| Datenmodellierung | Schema-Design, Normalisierungsentscheidungen, Caching-Strategie |
| Infrastruktur | Bereitstellungsmodell, CI/CD-Pipeline, Monitoring-Stack |
| Sicherheit | Auth-Strategie, Verschlüsselungsansatz, Geheimnisverwaltung |
| Tests | Test-Framework, Abdeckungsziele, E2E- vs. Integration-Test-Ausgleich |
| Prozess | Branching-Strategie, Review-Prozess, Release-Rhythmus |
Integration mit anderen Skills
- Planer-Agent: wenn der Planer Architekturänderungen vorschlägt, das Erstellen einer ADR vorschlagen
- Code-Reviewer-Agent: PRs markieren, die Architekturänderungen ohne entsprechende ADR einführen