AIDive

Video-Paket

KI-Specs und Pläne in Git steuern: fünf Regeln, Drift-Gate, Quellen und Checkliste

11 Min. Lesezeit

TL;DR

  • Committe KI-geschriebene Specs und Pläne. Jedes Tool tut das schon standardmäßig; offen ist nur die Governance.
  • Gib jedem Squad einen Ordner mit einer CODEOWNERS-Zeile, damit eine Spec-Änderung ein Review der Code-Owner anfordert.
  • Setze auf jede geteilte Spec einen Header im ADR-Stil: Status, superseded-by, Owner, betroffene Pfade, Review-Datum. Schreibe eine akzeptierte Spec nie zu einer neuen Entscheidung um.
  • Lass in der CI ein Drift-Gate laufen: Für jede akzeptierte Spec schlägt der Build fehl, sobald ein genannter Pfad nicht mehr existiert.
  • Leite den Ausgabepfad mit einer fett gesetzten Imperativzeile in CLAUDE.md um, halte persönliche Pläne in CLAUDE.local.md und .git/info/exclude und schreibe auf einem Branch, nie auf main.
  • Schreibe nur dann eine Spec, wenn die Arbeit eine Squad-Grenze überschreitet oder in 90 Tagen noch einmal gelesen wird. Spec-getriebene Läufe kosten etwa doppelt so viel Zeit und dreimal so viele Tokens.

Was die Quellen sagen

Die Defaults: alle committen

Der writing-plans-Skill von Superpowers speichert Pläne unter docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, mit einer Zeile darunter, dass Nutzereinstellungen zum Planort diesen Default überschreiben s1. Der brainstorming-Skill schreibt das validierte Design nach docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md und endet mit "Commit the design document to git" s2. Spec Kit legt specs/[branch-name]/ mit spec.md, plan.md und tasks.md an, nummeriert 001, 002, dazu eine Constitution in memory/constitution.md s6. Kiro führt .kiro/specs/ mit einem Ordner pro Feature und lädt Teams ein, "collaborate with team members on different features simultaneously" s8. Das Playbook von Anthropic ist eindeutig: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md" und "When implementation departs from the plan, update plan.md in the same commit" s5.

Keines dieser Dokumente sagt, wem eine committete Spec gehört oder wann sie aufhört, wahr zu sein. In dieser Lücke liegen die drei dokumentierten Fehlschläge.

Fehler 1: das öffentliche Leak

Issue 1690, eröffnet am 2026-06-05, meldet, dass der Standardort docs/superpowers/ interne Pläne über Sphinx und Read the Docs in die veröffentlichte Dokumentation durchsickern lassen kann s15. Betroffen war okama, eine Python-Bibliothek mit 273 Sternen. Der Fix-Commit hat 5 Pläne und 3 Specs wieder hinzugefügt, eine .gitignore-Zeile entfernt und lautet "track superpowers plans/specs in git, excluded from the Sphinx build" s21. In Zeile 84 von docs/conf.py steht jetzt exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Heute enthält der Ordner 8 Pläne und 6 Specs s15. Das Team hat die Praxis behalten und den Build repariert.

Fehler 2: Pläne auf main

Issue 1246, eröffnet am 2026-04-22 und noch offen, fragt, warum der Plan committet wird, bevor ein Entwicklungs-Branch existiert. Ein Nutzer berichtet "I'm getting 10 to 15 commits"; ein anderer: "Yes please, no plans and specs on main branch!" s16. Das Plugin erzwingt keine Branch-Regel; die Checkliste unten tut es.

Fehler 3: Overrides, die das Modell überspringt

Issue 337 wurde am 2026-03-10 geschlossen, mit dem Hinweis des Maintainers, dass das Plugin seit v5.0 die CLAUDE.md deines Projekts über seine eigenen Defaults stellt, Beispielzeile: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. Issue 939 auf v5.0.6 zeigt die Grenze: Eine "Output Paths"-Tabelle in CLAUDE.md wurde ignoriert, und Specs landeten weiter in docs/superpowers/specs/. Der Workaround, der funktionierte, ist eine fett gesetzte Imperativzeile unter der Tabelle: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. Pull Request 1020, der die Anweisung umsortierte, wurde ohne Merge geschlossen s19. Der Override ist ein Prompt, keine Einstellung: Prüfe ihn nach jedem Plugin-Release neu. Für die eigenen Scratch-Dateien des Plugins wurde Issue 1780 mit v6.0.3 geschlossen, durch einen sich selbst ignorierenden Ordner .superpowers/sdd/, der seine eigene .gitignore mit * ablegt s20.

Persönlich versus geteilt

Claude Code dokumentiert die Trennung: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. CLAUDE.md-Dateien pro Verzeichnis werden bei Bedarf geladen, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", und eine Einstellung claudeMdExcludes blendet in einem Monorepo die Dateien anderer Teams aus s4. Git kennt drei Ignore-Ebenen, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude und .gitignore s24; die mittlere versteckt einen persönlichen Pläne-Ordner, ohne eine geteilte Datei anzufassen. CODEOWNERS erledigt die Ownership-Hälfte: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Lebenszyklus, wie bei ADRs

Michael Nygards Post von 2011 ist die Vorlage: Eine Entscheidung "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement", und "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. Thoughtworks teilt die Spec-Nutzung in spec-first (einmal für die Aufgabe geschrieben), spec-anchored (behalten, um das Feature weiterzuentwickeln) und spec-as-source (nur die Spec wird bearbeitet), und der Autor ergänzt: "I'd rather review code than all these markdown files" s10. Superpowers schreibt spec-first-Dateien und behält sie für immer: Drift per Default.

Drift und das Gate

Das arXiv-Paper nennt das Problem "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" und schlägt vor: "a drift gate that makes spec-code divergence a blocking merge condition" s11. Der Guide von Spec Kit warnt: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry bringt den Governance-Fall auf den Punkt: "forty-one specs and nine agent files aren't a tidiness problem", es sind "forty-one unversioned behavior inputs and nine competing standing policies", und Drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". Derselbe Post empfiehlt etwa 300 Zeilen pro Spec und ein Budget von 150 bis 200 ständigen Anweisungen s13. Ein Praktiker beschreibt die manuelle Variante: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

Was es kostet

Experiment Ergebnis Quelle
Spec Kit bei einem Feature, das das aktuelle Datum anzeigt 8 Dateien und 1,300 Zeilen Text s14
OpenSpec-Bake-off, gleiche Anforderungen, Spec-Tool gegen reines Claude Code OpenSpec fand 3 Lücken mehr; 50% mehr Code mit 50% mehr zyklomatischer Komplexität; doppelt so lang und dreimal so teuer s12
Ein Team, das monatelang spec-getrieben entwickelt "two to three times as many tokens and take about twice as long"; kein Beleg, dass der Code besser wurde s25

Der Bake-off ist ein einzelnes Experiment und sein Autor sagt das selbst, aber die Richtung stimmt in allen drei überein. Also: Spec den architektonischen Pfad, halte den begrenzten Pfad begrenzt, und befolge die zwei Zeilen, die Praktiker wiederholen: "don t spec too big / read the generated specs" s26.

Das ist am Montag zu tun

  • Lege pro Squad docs/specs/<squad>/ an und füge pro Ordner eine CODEOWNERS-Zeile hinzu, die auf die Reviewer dieses Squads zeigt.
  • Füge der CLAUDE.md des Projekts eine fett gesetzte Imperativzeile hinzu: plans and specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Führe ein Brainstorming aus und prüfe, wo die Datei gelandet ist.
  • Verschiebe persönliche Pläne in einen Ordner, der in .git/info/exclude steht, und halte Einstellungen pro Entwickler in CLAUDE.local.md, das selbst ignoriert wird.
  • Setze auf jede geteilte Spec einen Header: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
  • Schreibe das Drift-Gate: Extrahiere für jede Spec mit status: accepted die genannten Pfade und lass den Pull Request fehlschlagen, wenn einer fehlt. Etwa fünfzehn Zeilen Shell oder Python.
  • Füge eine Branch-Regel hinzu: Kein Spec- oder Plan-Commit landet auf main außerhalb eines Pull Requests.
  • Wenn das Repo Docs mit Sphinx oder Ähnlichem veröffentlicht, nimm den Specs-Ordner noch heute in exclude_patterns auf.
  • Lege das Größenbudget fest: Eine Spec bleibt bei etwa 300 Zeilen, und nur Arbeit, die eine Squad-Grenze überschreitet oder nach 90 Tagen noch einmal gelesen wird, bekommt eine.

Weiterlesen

  • Lies die drei Spec-Kategorien (spec-first, spec-anchored, spec-as-source), bevor du ein Header-Schema wählst; der Lebenszyklus ist nur für spec-anchored-Dateien relevant s10.
  • Das arXiv-Paper geht über Pfadprüfungen hinaus bis zu einer vollständig drift-erzwingenden Architektur; nützlich, sobald das Fünfzehn-Zeilen-Gate zu grob wirkt s11.
  • Der Guide von Spec Kit nennt drei Evolutionsabläufe (Flow-Forward, Living Spec, Flow-Back), die sich auf die Same-Commit-Regel abbilden lassen s7.
  • Das Playbook schlägt einen Hook vor, der die Synchronität von Plan und Diff erzwingt; der Reddit-Thread dazu hat 43 Punkte und 27 Kommentare mit Praxisberichten s5, s27.
  • Das Argument von TrueFoundry, dass eine Spec-Änderung eine Policy-Änderung ist und deshalb hinter ein Eval-Gate mit Run-Metadaten gehört, ist der nächste Schritt nach CI-Pfadprüfungen s13.
  • Verfolge die zwei offenen Issues, 1246 (Pläne auf main) und 939 (ignorierte Overrides); wenn eines schließt, wird eine Regel dieses Packs zum Plugin-Default s16, s18.
  • Der vollständige Beitrag von Marmelab erklärt, warum die 1,300 Zeilen entstanden und wo Spec Kit sich lohnt s14.

Quellen

FAQ

Brauche ich alle fünf Regeln von Tag eins an?

Nein. Die CLAUDE.md-Umleitung und der Sphinx-Ausschluss dauern zehn Minuten. Füge CODEOWNERS und den Header hinzu, sobald eine Spec zum ersten Mal Squads überschreitet, und das Drift-Gate, sobald eine akzeptierte Spec einen Sprint alt ist.

Was übersieht das Drift-Gate?

Geändertes Verhalten. Es prüft nur, ob ein genannter Pfad noch existiert, eine umgekehrte Bedingung kommt also durch. Kombiniere es mit der Same-Commit-Regel und mit Review.

Warum nicht einfach den Ordner ignorieren?

Weil der Agent, der die Spec später liest, sie braucht, und der Audit Trail nur funktioniert, wenn die Zwischenstücke versioniert sind. Das okama-Team hat das gitignore versucht und ist zum Committen mit Build-Ausschluss zurückgekehrt.