clanker25/ai

# ADR Skill

## Philosophie

Mit diesem Skill erstellte ADRs sind **ausführbare Spezifikationen für Codierungsagenten**. Ein Mensch genehmigt die Entscheidung; ein Agent setzt sie um. Das ADR muss alles enthalten, was der Agent benötigt, um korrekten Code zu schreiben, ohne Rückfragen stellen zu müssen.

Das bedeutet:

- Einschränkungen müssen explizit und messbar sein, keine vagen Vorstellungen
- Entscheidungen müssen konkret genug sein, um darauf zu handeln ("PostgreSQL 16 mit pgvector verwenden", nicht "eine Datenbank verwenden")
- Konsequenzen müssen konkreten Folgeaufgaben zugeordnet werden können
- Nicht-Ziele müssen angegeben werden, um Scope Creep zu verhindern
- Das ADR muss in sich geschlossen sein – keine Annahmen von implizitem Wissen
- **Das ADR muss einen Implementierungsplan enthalten** – welche Dateien zu bearbeiten sind, welche Muster zu befolgen sind, welche Tests zu schreiben sind und wie überprüft werden kann, ob die Entscheidung korrekt umgesetzt wurde

## Wann ein ADR geschrieben werden sollte

Schreibe ein ADR, wenn eine Entscheidung:

- **Ändert, wie das System gebaut oder betrieben wird** (neue Abhängigkeit, Architekturmuster, Infrastrukturentscheidung, API-Design)
- **Schwer rückgängig zu machen ist**, sobald Code dagegen geschrieben wurde
- **Andere Personen oder Agenten betrifft**, die später in dieser Codebasis arbeiten werden
- **Echte Alternativen hat**, die in Betracht gezogen und verworfen wurden

Schreibe KEIN ADR für:

- Routinemäßige Implementierungsentscheidungen innerhalb eines etablierten Musters
- Fehlerbehebungen oder Tippfehlerkorrekturen
- Bereits in einem bestehenden ADR erfasste Entscheidungen (aktualisiere es stattdessen)
- Stilpräferenzen, die bereits von Linters oder Formatierern abgedeckt werden

Im Zweifelsfall: Wenn ein zukünftiger Agent, der in dieser Codebasis arbeitet, davon profitieren würde zu wissen, _warum_ diese Wahl getroffen wurde, schreibe das ADR.

### Proaktive ADR-Auslöser (für Agenten)

Wenn du ein Agent bist, der in einem Repository codiert, und du auf eine dieser Situationen stößt, **halte an und schlage ein ADR vor**, bevor du fortfährst:

- Du stehst kurz davor, eine neue Abhängigkeit einzuführen, die im Projekt noch nicht existiert
- Du stehst kurz davor, ein neues Architekturmuster zu erstellen (neue Art der Fehlerbehandlung, neue Datenzugriffsschicht, neue API-Konvention), dem anderer Code folgen muss
- Du stehst kurz davor, eine Wahl zwischen zwei oder mehr echten Alternativen zu treffen, und die Abwägungen sind nicht offensichtlich
- Du stehst kurz davor, etwas zu ändern, das einem bestehenden akzeptierten ADR widerspricht
- Du stellst fest, dass du einen langen Codekommentar schreibst, der "warum" erklärt – diese Begründung gehört in ein ADR

**So schlägst du vor**: Sage dem Menschen, auf welche Entscheidung du gestoßen bist, warum sie wichtig ist, und frage, ob sie diese als ADR erfassen möchten. Wenn ja, führe den vollständigen Vier-Phasen-Workflow aus. Wenn nein, notiere die Entscheidung in einem Codekommentar und fahre fort.

## Erstellen eines ADR: Vier-Phasen-Workflow

Jedes ADR durchläuft vier Phasen. Überspringe keine Phasen.

### Phase 0: Durchsuche die Codebasis

Bevor du Fragen stellst, sammle Kontext aus dem Repository:

1. **Finde bestehende ADRs.** Überprüfe `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/` auf vorhandene Aufzeichnungen. Lies sie. Notiere:
   - Bestehende Konventionen (Verzeichnis, Namensgebung, Vorlagenstil)
   - Entscheidungen, die sich auf die aktuelle beziehen oder sie einschränken
   - Alle ADRs, die diese neue Entscheidung möglicherweise ersetzt

2. **Überprüfe den Tech-Stack.** Lies `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml` oder Äquivalent. Notiere relevante Abhängigkeiten und Versionen.

3. **Finde verwandte Codemuster.** Wenn die Entscheidung einen bestimmten Bereich betrifft (z. B. "wie wir Auth handhaben"), suche nach vorhandenen Implementierungen. Identifiziere die spezifischen Dateien, Verzeichnisse und Muster, die von der Entscheidung betroffen sein werden.

4. **Überprüfe auf ADR-Referenzen im Code.** Suche nach ADR-Referenzen in Kommentaren und Dokumentationen (siehe "Code ↔ ADR-Verknüpfung" unten). Dies zeigt, welche bestehenden Entscheidungen welche Teile der Codebasis regeln.

5. **Notiere, was du gefunden hast.** Nimm diesen Kontext in Phase 1 mit – er wird deine Fragen schärfen und verhindern, dass das ADR bestehenden Entscheidungen widerspricht.

### Phase 1: Absicht erfassen (Sokratisch)

Befrage den Menschen, um den Entscheidungsraum zu verstehen. Stelle Fragen **einzeln**, die auf vorherigen Antworten aufbauen. Gib keine Liste von Fragen auf einmal aus.

**Kernfragen** (stelle sie ungefähr in dieser Reihenfolge; überspringe, was aus dem Kontext oder Phase 0 bereits klar ist):

1. **Worüber entscheidest du?** – Erhalte einen kurzen, spezifischen Titel. Dränge auf eine Verbphrase ("X wählen", "Y übernehmen", "Z durch W ersetzen").
2. **Warum jetzt?** – Was ist kaputt, was ändert sich oder was wird kaputtgehen, wenn du nichts tust? Dies ist der Auslöser.
3. **Welche Einschränkungen gibt es?** – Tech-Stack, Zeitplan, Budget, Teamgröße, vorhandener Code, Compliance. Sei konkret. Verweise auf das, was du in Phase 0 gefunden hast ("Ich sehe, dass Sie bereits X verwenden – schränkt das dies ein?").
4. **Wie sieht Erfolg aus?** – Messbare Ergebnisse. Gehe über „es funktioniert“ hinaus zu Details (Latenz, Durchsatz, DX, Wartungsaufwand).
5. **Welche Optionen hast du in Betracht gezogen?** – Mindestens zwei. Für jede: Was ist der Kernabwägung? Wenn sie nur eine Option haben, hilf ihnen zu formulieren, warum Alternativen verworfen wurden.
6. **Was ist deine derzeitige Neigung?** – Erfasse die Bauchgefühl-Intuition frühzeitig. Offenbart oft nicht genannte Prioritäten.
7. **Wer muss davon wissen oder es genehmigen?** – Entscheidungsträger, konsultierte Experten, informierte Stakeholder.
8. **Was bräuchte ein Agent, um dies zu implementieren?** – Welche Dateien/Verzeichnisse sind betroffen? Welchen vorhandenen Mustern sollte es folgen? Was sollte es vermeiden? Welche Tests würden beweisen, dass es funktioniert? Dies fließt direkt in den Implementierungsplan ein.

**Adaptive Folgefragen:** Basierend auf den Antworten, vertiefe dich dort, wo die Entscheidung unscharf ist. Häufige Folgefragen:

- „Was ist das schlechteste Ergebnis, wenn diese Entscheidung falsch ist?“
- „Was würde dich dazu bringen, dies in 6 Monaten zu überdenken?“
- „Gibt es etwas, das du explizit NICHT tun wirst?“
- „Auf welche früheren Arbeiten oder bestehenden Muster in der Codebase bezieht sich dies?“
- „Ich habe [existierendes ADR/Muster] gefunden – interagiert diese neue Entscheidung damit?“

**Wann aufhören:** Du hast genug, wenn du jeden Abschnitt des ADR ausfüllen kannst – einschließlich des Implementierungsplans – ohne etwas zu erfinden. Wenn du bei einem Abschnitt rätst, stelle eine weitere Frage.

**Absichtserklärungs-Tor:** Bevor du zu Phase 2 übergehst, präsentiere eine strukturierte Zusammenfassung dessen, was du erfasst hast, und bitte den Menschen, sie zu bestätigen oder zu korrigieren:

> **Hier ist, was ich für das ADR erfasse:**
>
> - **Titel**: {Titel}
> - **Auslöser**: {warum jetzt}
> - **Einschränkungen**: {Liste}
> - **Optionen**: {Option 1} vs. {Option 2} [vs. ...]
> - **Neigung**: {welche Option und warum}
> - **Nicht-Ziele**: {was explizit ausgeschlossen ist}
> - **Verwandte ADRs/Code**: {was existiert, womit dies interagiert}
> - **Betroffene Dateien/Bereiche**: {wo in der Codebase dies landet}
> - **Verifikation**: {wie wir wissen, dass es korrekt implementiert ist}
>
> **Erfasst dies deine Absicht? Möchtest du etwas hinzufügen oder korrigieren?**

Fahre NICHT mit Phase 2 fort, bis der Mensch die Zusammenfassung bestätigt hat.

### Phase 2: Entwurf des ADR

1. **Wähle das ADR-Verzeichnis.**
   - Wenn eines existiert (in Phase 0 gefunden), verwende es.
   - Wenn keines existiert, erstelle `contributing/decisions/` (falls `contributing/` existiert), `docs/decisions/` (MADR-Standard) oder `adr/` (einfachere Repos).

2. **Wähle eine Dateinamensstrategie.**
   - Wenn vorhandene ADRs Datumspräfixe verwenden (`YYYY-MM-DD-...`), führe diese fort.
   - Andernfalls verwende Dateinamen nur aus einem Slug (`choose-database.md`).

3. **Wähle eine Vorlage.**
   - Verwende `assets/templates/adr-simple.md` für einfache Entscheidungen (ein klarer Gewinner, minimale Abwägungen).
   - Verwende `assets/templates/adr-madr.md`, wenn du mehrere Optionen mit strukturierten Vor-/Nachteilen/Treibern dokumentieren musst.
   - Siehe `references/template-variants.md` für Anleitungen.

4. **Fülle jeden Abschnitt aus der bestätigten Absichtserklärung aus.** Lasse keinen Platzhaltertext. Jeder Abschnitt sollte echten Inhalt enthalten oder entfernt werden (nur optionale Abschnitte).

5. **Schreibe den Implementierungsplan.** Dies ist der wichtigste Abschnitt für agentenorientierte ADRs. Er sagt dem nächsten Agenten genau, was zu tun ist. Siehe die Vorlage für die Struktur.

6. **Schreibe Verifikationskriterien als Kontrollkästchen.** Diese müssen spezifisch genug sein, dass ein Agent jedes einzelne programmatisch oder manuell überprüfen kann.

7. **Generiere die Datei.**
   - Bevorzugt: Führe `scripts/new_adr.js` aus (handhabt Verzeichnis, Benennung und optionale Indexaktualisierungen).
   - Wenn du keine Skripte ausführen kannst, kopiere eine Vorlage aus `assets/templates/` und fülle sie manuell aus.

### Phase 3: Überprüfung anhand der Checkliste

Nach dem Entwurf überprüfe das ADR anhand der Agenten-Ready-Checkliste in `references/review-checklist.md`.

**Präsentiere die Überprüfung als Zusammenfassung**, nicht als Rohdaten-Dump der Checkliste. Format:

> **ADR-Überprüfung**
>
> ✅ **Besteht**: {Liste, was solide ist – z. B. "Kontext ist in sich geschlossen, Implementierungsplan deckt betroffene Dateien ab, Verifikationskriterien sind überprüfbar"}
>
> ⚠️ **Gefundene Lücken**:
>
> - {spezifische Lücke 1 – z. B. "Implementierungsplan erwähnt keine Testdateien – welche Testsuite sollte dies abdecken?"}
> - {spezifische Lücke 2}
>
> **Empfehlung**: {Abschicken / Zuerst die Lücken beheben / Mehr Arbeit in Phase 1 erforderlich}

Mache nur auf Fehler und bemerkenswerte Stärken aufmerksam – rezitiere nicht jeden bestandenen Prüfpunkt.

Wenn es Lücken gibt, schlage spezifische Korrekturen vor. Markiere nicht nur Probleme – biete Lösungen an und bitte den Menschen um Genehmigung.

Schließe nicht ab, bis das ADR die Checkliste besteht oder der Mensch die Lücken explizit akzeptiert.

## ADRs konsultieren (Lese-Workflow)

Agenten sollten vorhandene ADRs **vor der Implementierung von Änderungen** in einer Codebasis lesen, die sie enthält. Dies ist nicht Teil des ADR-Erstellungs-Workflows – es ist ein eigenständiger Vorgang, den jeder Agent ausführen sollte.

### Wann ADRs konsultiert werden sollten

- Bevor du mit der Arbeit an einer Funktion beginnst, die die Architektur betrifft (Auth, Datenebene, API-Design, Infrastruktur)
- Wenn du auf ein Muster im Code stößt und dich fragst "warum wird es so gemacht?"
- Bevor du eine Änderung vorschlägst, die einer bestehenden Entscheidung widersprechen könnte
- Wenn ein Mensch sagt "überprüfe die ADRs" oder "es gibt eine Entscheidung dazu"
- Wenn du einen ADR-Verweis in einem Codekommentar findest

### Wie ADRs konsultiert werden

1. **Finde das ADR-Verzeichnis.** Überprüfe `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/`. Überprüfe auch auf eine Indexdatei (`README.md` oder `index.md`).

2. **Scanne Titel und Status.** Lies den Index oder liste die Dateinamen auf. Konzentriere dich auf `accepted` ADRs – dies sind aktive Entscheidungen.

3. **Lese relevante ADRs vollständig.** Lies nicht nur den Titel – lies Kontext, Entscheidung, Konsequenzen, Nicht-Ziele UND den Implementierungsplan. Der Implementierungsplan sagt dir, welchen Mustern du folgen sollst und welche Dateien von dieser Entscheidung betroffen sind.

4. **Respektiere die Entscheidungen.** Wenn ein akzeptiertes ADR sagt "verwende PostgreSQL", schlage nicht vor, zu MongoDB zu wechseln, ohne ein neues ADR zu erstellen, das es ersetzt. Wenn du einen Konflikt zwischen dem, was der Code tut, und dem, was das ADR sagt, feststellst, melde dies dem Menschen.

5. **Befolge den Implementierungsplan.** Wenn du Code in einem Bereich implementierst, der von einem ADR geregelt wird, befolge die in seinem Implementierungsplan festgelegten Muster. Wenn der Plan sagt "alle neuen Abfragen gehen durch die Datenzugriffsschicht in `src/db/`", tue das.

6. **Verweise auf ADRs in deiner Arbeit.** Füge ADR-Verweise in Codekommentare und PR-Beschreibungen ein (siehe "Code ↔ ADR-Verknüpfung" unten).

## Code ↔ ADR-Verknüpfung

ADRs sollten bidirektional mit dem Code verknüpft sein, den sie regeln.

### ADR → Code (im Implementierungsplan)

Der Abschnitt Implementierungsplan nennt spezifische Dateien, Verzeichnisse und Muster:

```markdown
## Implementierungsplan

- **Betroffene Pfade**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Muster**: Alle Datenbankabfragen gehen durch `src/db/client.ts`

Code → ADR (in Kommentaren)

Wenn du Code implementierst, der von einem ADR geleitet wird, füge einen Kommentar hinzu, der darauf verweist:

// ADR: Using better-sqlite3 for test database
// See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

Halte diese leichtgewichtig – ein Kommentar am Einstiegspunkt, nicht in jeder Zeile. Das Ziel ist Auffindbarkeit: Wenn ein zukünftiger Agent diesen Code liest, kann er die Begründung finden.

Warum dies wichtig ist

• Ein Agent, der in src/db/ arbeitet, kann finden, welche ADRs diesen Bereich regeln
• Ein Agent, der ein ADR liest, kann den Code finden, der es implementiert
• Wenn ein ADR ersetzt wird, erleichtern die Codeverweise das Auffinden aller zu aktualisierenden Codes

Andere Operationen

Vorhandenes ADR aktualisieren

1. Identifiziere die Absicht:

   • Akzeptieren / ablehnen: ändere den Status, füge ggf. abschließenden Kontext hinzu.
   • Veralten: Status → deprecated, erkläre den Ersatzpfad.
   • Ersetzen: erstelle ein neues ADR, verlinke beide Wege (alt → neu, neu → alt).
   • Erkenntnisse hinzufügen: füge unter ## Weitere Informationen mit einem Datumsstempel hinzu. Überschreibe keine Geschichte.

2. Verwende scripts/set_adr_status.js für Statusänderungen (unterstützt YAML-Frontmatter, Aufzählungsstatus und Abschnittsstatus).

Lebenszyklus nach der Annahme

Nachdem ein ADR angenommen wurde:

1. Erstelle Implementierungsaufgaben. Jeder Punkt im Implementierungsplan und jede Nachverfolgung in den Konsequenzen sollte zu einer nachverfolgbaren Aufgabe werden (Issue, Ticket oder TODO).
2. Verweise auf das ADR in PRs. Verlinke das ADR in PR-Beschreibungen, z. B. "Implementiert contributing/decisions/2025-06-15-use-sqlite-for-test-database.md."
3. Füge Codeverweise hinzu. Füge ADR-Pfadkommentare an wichtigen Implementierungspunkten hinzu.
4. Überprüfe die Verifikationskriterien. Wenn die Implementierung abgeschlossen ist, gehe die Verifikationskontrollkästchen durch. Aktualisiere das ADR mit Ergebnissen unter ## Weitere Informationen.
5. Überprüfe erneut, wenn Auslöser eintreten. Wenn das ADR Bedingungen für eine erneute Überprüfung festgelegt hat ("wenn X passiert, überdenken"), überwache auf diese Bedingungen.

Index

Wenn das Repository eine ADR-Index-/Protokolldatei hat (oft README.md oder index.md im ADR-Verzeichnis), halte sie auf dem neuesten Stand.

Bevorzugt: Lass scripts/new_adr.js --update-index dies erledigen. Andernfalls:

• Füge einen Aufzählungspunkt für das neue ADR hinzu.
• Halte die Reihenfolge konsistent (numerisch, wenn nummeriert; Datum oder alphabetisch, wenn Slugs).

Bootstrap

Wenn du ADRs in ein Repository einführst, das noch keine hat:

node /path/to/adr-skill/scripts/bootstrap_adr.js

Dies erstellt das Verzeichnis, eine Indexdatei und ein ausgefülltes erstes ADR ("Adopt architecture decision records") mit echtem Inhalt, der erklärt, warum das Team ADRs verwendet. Verwende --json für maschinenlesbare Ausgabe. Verwende --dir, um den Verzeichnisnamen zu überschreiben.

Kategorien (Große Projekte)

Für Repos mit vielen ADRs organisiere nach Unterverzeichnissen:

docs/decisions/
  backend/
    2025-06-15-use-...