Kristian
99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
---
|
|
name: adr
|
|
description: 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.
|
|
disable-model-invocation: true
|
|
argument-hint: "<titel der entscheidung, z. b.: 'pocketbase statt supabase'>"
|
|
allowed-tools:
|
|
- 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:
|
|
|
|
```markdown
|
|
- [{{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`.
|