claude-code-workflow/global-skills/adr/SKILL.md

name, description, disable-model-invocation, argument-hint, allowed-tools

name	description	disable-model-invocation	argument-hint	allowed-tools
adr	Legt unter docs/30-decisions/ einen neuen Architecture Decision Record an, automatisch hochnummeriert, nach festem Template (Context, Decision, Consequences, Alternatives). Ergänzt gleichzeitig den Abschnitt "Laufende ADRs" in docs/20-architecture.md.	true	<titel der entscheidung, z. b.: 'pocketbase statt supabase'>	Read Write Edit Bash

adr — Architecture Decision Record

Wann der Skill läuft

Immer dann, wenn eine Entscheidung getroffen wird, die später Kopfschmerzen kostet, wenn sie niemand dokumentiert. Typische Beispiele:

• Wahl einer Technologie gegen Alternativen („PocketBase statt Supabase").
• Struktur-Entscheidung, die konkurrierende Optionen hatte („Monorepo statt mehrerer Repos", „Events statt direktem Call").
• Betriebs-Entscheidung mit Tragweite („Caddy als Reverse-Proxy", „tägliches Snapshot-Backup auf Hetzner Storage Box").

Nicht für triviale Entscheidungen („wir benennen die Variable user_id statt uid") — da ist der ADR mehr Last als Nutzen.

Voraussetzungen

Existiert docs/30-decisions/? Wenn nicht → meldet „Kein initialisiertes Projekt. Erst plan-start ausführen." Abbrechen.

Was der Skill tut

Schritt 1 — Titel bestimmen

• Titel kommt aus $ARGUMENTS. Wenn leer: freundlich nach einem Titel fragen (eine Zeile), nicht weiter spekulieren.
• Slug aus Titel ableiten: lowercase, Leerzeichen → Bindestrich, Sonderzeichen raus. Beispiel: PocketBase statt Supabase → pocketbase-statt-supabase.

Schritt 2 — Nummer vergeben

• ls docs/30-decisions/ | grep -E '^[0-9]{4}-' listet bestehende ADRs.
• Höchste bestehende Nummer + 1, auf 4 Stellen gepaddet (0001, 0042).
• Erste ADR → 0001.

Schritt 3 — Datei anlegen

• Dateiname: docs/30-decisions/<NNNN>-<slug>.md.
• Inhalt: aus templates/adr.md.tmpl, Platzhalter füllen:

Platzhalter	Quelle
{{ADR_NUMBER}}	die vergebene Nummer, 4-stellig
{{ADR_TITLE}}	der Titel
{{ADR_DATE}}	date +%F
{{ADR_AUTHOR}}	git config user.name, sonst leer

Status ist initial proposed. Der Nutzer wechselt ihn später auf accepted, wenn die Entscheidung gelebt wird — oder auf superseded by NNNN, wenn ein späterer ADR sie ablöst.

Schritt 4 — Abschnitt „Laufende ADRs" in 20-architecture.md ergänzen

Am Ende von docs/20-architecture.md steht ein Abschnitt ## Laufende ADRs. Dort wird eine Zeile nach folgendem Muster angehängt:

- [{{ADR_NUMBER}}](30-decisions/{{ADR_NUMBER}}-{{slug}}.md) — {{ADR_TITLE}} (`proposed`, {{ADR_DATE}})

Wenn dort noch der Platzhalter-Text _(Noch keine ADRs. ...)_ steht: diesen entfernen und die erste Zeile einfügen.

Schritt 5 — Kurze Bestätigung

Dem Nutzer den neuen Pfad und die Nummer zurückmelden, und einen knappen Hinweis: „Datei ist als proposed markiert. Wenn die Entscheidung steht: auf accepted setzen."

Harte Regeln

• Nie einen bestehenden ADR überschreiben. Nummerierung ist append-only.
• Nie den Status eines anderen ADR ändern. Wenn der neue ADR einen alten ablöst: das trägt der Nutzer selbst am alten ADR nach (im neuen ADR sollte er es im Header Supersedes: NNNN notieren — aber auch das macht der Nutzer, der Skill verdrahtet das nicht automatisch, weil das Fehlerquelle ist).
• Keine Entscheidung erfinden. Der Skill legt nur das Gerüst an. Context / Decision / Consequences füllt der Nutzer. Der Skill darf ruhig Vorschläge machen, wenn im Chatkontext genug Information da ist — aber er schreibt nichts in die Datei, was der Nutzer nicht bestätigt hat.

Template

Siehe ./templates/adr.md.tmpl.