Entscheidungen aufzeichnen
Übersicht
Entscheidungen sind dauerhafte Infrastruktur; Gedächtnis und Chat-Verlauf sind es nicht. Die Kosten einer Aufzeichnung werden einmalig bezahlt; die Kosten einer verlorenen Entscheidung werden jedes Mal bezahlt, wenn jemand die Absicht aus Code rückentwickelt.
Die Form der Aufzeichnung
Jede nicht-triviale Entscheidung erzeugt eine Aufzeichnung mit einer festen Struktur, sodass jeder Leser weiß, wo er suchen muss:
| Abschnitt | Enthält |
|---|---|
| Architektur | Die Form der Lösung und die Schlüsseldateien |
| Datenmodell | Entitäten, Felder, Beziehungen |
| Entscheidungen (mit WARUM) | Jede Wahl zusammen mit ihrer Begründung – warum ist Pflicht |
| Schnittstellen | Wie anderer Code dies verwendet |
| Einschränkungen | Was muss wahr bleiben |
| Fallstricke | Nicht offensichtliche Fallen für die nächste Person |
| Abgelehnte Alternativen | Was wurde erwogen und verworfen, und warum – verhindert das Wiederaufgreifen geklärter Fragen |
Die drei Begleitartefakte
- Ein Index aller Entscheidungen mit expliziter Abhängigkeitsverfolgung (welche auf welcher aufbaut) und einem Abschnitt Ersetzt. Verwandelt einen Haufen Aufzeichnungen in einen navigierbaren Graphen.
- Ein Dokument „Zukünftige Überlegungen“ – zurückgestellte Ideen und bekannte Anliegen, das bei Beginn neuer Arbeiten konsultiert wird, damit nichts stillschweigend vergessen wird. Incident-Aktionspunkte und zurückgestellte Entscheidungen mit Auslöser landen hier.
- Ein Archiv – ersetzte Aufzeichnungen werden hierhin verschoben, anstatt gelöscht zu werden. Die Geschichte bleibt erhalten, nicht überschrieben.
Kurzreferenz
- Aufzeichnungsort-Konvention:
docs/superpowers/decisions/YYYY-MM-DD-<thema>.mdmit YAML-Frontmatter (title,date,component,status,supersedes,dependencies). - Zukünftige Überlegungen befinden sich unter
docs/superpowers/future-considerations.md. Jeder Eintrag trägt einen Status (open/triggered/done/dropped) und, wo zutreffend, den Auslöser , der ihn reaktivieren soll. Konsultieren Sie ihn bei Beginn neuer Arbeiten. - Frontmatter speist den automatisch generierten Index – halten Sie es genau.
- Das Warum und die abgelehnten Alternativen sind die beiden wertvollsten Abschnitte. Eine Aufzeichnung ohne sie ist eine Zeitbombe.
- Schreiben Sie die Aufzeichnung im Aufzeichnungs -Schritt der Pipeline (siehe
designing-before-building), nach „Ausführen“.
Gebündelte Werkzeuge
Dieses Skill enthält eigene Skripte und Vorlagen, sodass sie in jedem Repository funktionieren, in dem das Skill installiert ist. Sie befinden sich neben SKILL.md:
recording-decisions/
scripts/doc-archive.sh findet Spezifikationen/Pläne ohne Entscheidungsprotokoll
scripts/index-rebuild.sh regeneriert den Index aus den Frontmatter-Daten
templates/decision-record.md
Finden Sie sie – das Skill kann pro Projekt oder global installiert sein:
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
Listet Spezifikationen ohne zugehöriges Entscheidungsprotokoll auf und gibt eine Konvertierungsaufforderung aus, die aus der Vorlage erstellt wurde. Standardmäßig unter docs/superpowers/{specs,plans,decisions,archive}.
index-rebuild.sh [decisions_dir] [output_file]
Überschreibt docs/superpowers/index.md aus den Frontmatter-Daten jeder Aufzeichnung – eine Aktive Tabelle (Komponente, Titel, Datum, Abhängigkeiten) und eine Tabelle „Ersetzt“ (Komponente, Titel, ersetzt durch). Vollständig neu generiert, daher niemals von Hand bearbeiten.
Beide sind ablauffreie Bash-Skripte: Ein Projekt, das dieses Skill verwendet, benötigt weder yq, jq noch einen Task-Runner. Wenn die Skripte fehlen, sind die obigen Verfahren in sich abgeschlossen – führen Sie die Arbeit direkt aus.
Warum dies für den Kontext wichtig ist
Spezifikationen und Pläne sind absichtlich ausführlich; sie sind für einen Menschen geschrieben, der der Argumentation folgt. Diese Ausführlichkeit belastet den Kontext jedes Mal, wenn Claude eine öffnet. Ein Entscheidungsprotokoll behält, was für die Weiterarbeit benötigt wird – Entscheidungen, das Warum, Schnittstellen, Einschränkungen, Fallstricke, abgelehnte Alternativen – in etwa 30-50 Zeilen, während die ursprüngliche Spezifikation in archive/ verschoben wird, wo sie für Menschen lesbar bleibt und nichts kostet, bis sie absichtlich geöffnet wird.
Wann NICHT verwenden
Triviale, offensichtliche Änderungen benötigen keine Aufzeichnung. Der Test: Würde später jemand fragen „Warum wurde das so gemacht?“ Wenn ja, zeichnen Sie es auf.
Vollständige Begründung: Artikel II der Verfassung, gebündelt unter engineering-constitution/references/engineering-constitution.md.