AIDiveZehn Entwickler, ein Docs-Ordner
Superpowers ist ein Claude-Code-Plugin (286.000 GitHub-Stars), dessen Skills Specs und Implementierungspläne als Markdown-Dateien schreiben und ins Repository committen. Standardmäßig landet jede dieser Dateien in einem einzigen Ordner, docs/superpowers/. Im Juni entdeckten die Maintainer von Okama, einer Python-Finance-Library, dass acht Implementierungspläne, die ein Agent dort geschrieben hatte, exakt so committet, wie das Plugin es vorsieht, als öffentliche Webseiten auf Read the Docs gerendert worden waren. Sie merkten es erst nach dem Release.
Nun skaliere das hoch: ein Frontend-Team aus zehn Entwicklern, vier Squads, ein Repository, und jeder Entwickler erzeugt diese Dateien. Drei Fragen landen auf dem Tisch des Leads. Was genau versionieren wir? Ist Drift ein Problem, wenn ein Spec einen Pfad nennt, der vor zwei Sprints gelöscht wurde? Und wer regiert den Ordner? Der Okama-Leak wurde nicht durch das Committen verursacht. Er wurde durch Committen ohne Regel verursacht. Dieser Artikel liefert fünf.
Jedes Tool committet die Dateien
Superpowers fragt nie, ob committet werden soll. Zeile 18 seines Planning-Skills speichert jeden Plan unter docs/superpowers/plans/, datiert, eine Datei pro Feature. Der Brainstorming-Skill schreibt das Design-Dokument und committet es im selben Schritt, bevor du den Plan überhaupt gesehen hast.
Das ist keine Eigenheit von Superpowers. Jedes größere spec-driven Tool trifft dieselbe Entscheidung:
| Tool | Herausgeber | Wo Specs liegen |
|---|---|---|
| Superpowers (286.000 Stars) | obra | docs/superpowers/, ein Ordner für alles |
| Spec Kit (136.000 Stars) | GitHub | ein durchnummerierter Ordner pro Feature, auf dem Branch dieses Features |
| Kiro | Amazon | .kiro/specs/, ein Ordner pro Feature |
| AI-native-SDLC-Playbook | Anthropic | ein committetes Artefakt pro Stufe: Intent, Spec, Plan, Diff, Review-Findings, Incident-Record |
Kiro verkauft Ordner pro Feature als Möglichkeit für Teammitglieder, gleichzeitig an unterschiedlichen Features zu arbeiten. Anthropics im August veröffentlichtes Playbook geht weiter: Jede Stufe committet ein Artefakt, das die nächste Stufe lesen kann. Die Frage war also nie, ob committet wird, und das Wohin beantwortet jedes Tool. Wer die Datei besitzt und wann sie tot ist, beantwortet keines. Genau diese Lücke schließen die fünf Regeln.
Drei Wege, wie es schiefgeht
Committete Pläne scheitern auf drei unterschiedliche Arten.
Fehler 1: der Docs-Generator. Ein Dokumentations-Build, der jede Markdown-Datei unter docs/ rendert, ob ein Inhaltsverzeichnis sie listet oder nicht, verschickt den Pläne-Ordner zusammen mit dem Handbuch. Genau das ist Okama passiert.
Fehler 2: der Branch. Superpowers-Issue 1246 berichtet, dass der Brainstorm den Plan direkt auf main committet. Ein Nutzer zählt 10 bis 15 Commits pro Session, alle paar Änderungen ein neuer. Die Bitte im Thread passt in eine Zeile: keine Pläne und Specs auf dem Main-Branch.
Fehler 3: Drift. Spec-Drift ist der leise Fehler: Der Code entwickelt sich weiter, der Spec nicht. Birgitta Böckeler von Thoughtworks nennt drei Stufen von spec-driven development:
| Stufe | Bedeutung |
|---|---|
| Spec-first | Geschrieben, einmal benutzt |
| Spec-anchored | Für die Lebensdauer des Features gepflegt |
| Spec-as-source | Der Mensch bearbeitet nur noch den Spec |
Superpowers schreibt spec-first-Dokumente und behält sie für immer. Standardmäßig bekommst du spec-anchored Storage mit First-Draft-Pflege: Niemand aktualisiert die Datei, und ein Agent liest sie im nächsten Quartal als Wahrheit. TrueFoundry bringt es auf den Punkt: Drift ist bei spec-first unvermeidlich und bei spec-anchored beherrschbar, aber nur wenn die Abweichung erkennbar ist.
Ein Repository mit 41 Specs und 9 Agent-Dateien hat kein Ordnungsproblem. Es hat 41 unversionierte Behavior-Inputs. Böckelers eigene Reaktion: Sie würde lieber Code reviewen als all diese Markdown-Dateien. Ein Plan, den niemand mehr lädt, ist Ballast. Ein Plan, den ein Agent lädt, ist eine Anweisung, und eine veraltete ist eine falsche Anweisung.
Regel 1: ein Zuhause pro Squad, mit Owners
Regel 1: Der Ordner hat einen Owner, und der Owner ist ein Squad, nicht das Plugin. Seit Version 5 respektiert Superpowers Anweisungen in der CLAUDE.md deines Projekts vor seinen eigenen Defaults. Sag, wohin Pläne gehen, und sie gehen dorthin.
Eine Tabelle mit Pfaden reicht allerdings nicht. In Issue 939 schrieb ein Nutzer eine Output-Paths-Tabelle, und das Modell folgte dem konkreten Pfad im Skill und überging die Tabelle. Der eigene Override-Hinweis des Skills ist ein Klammerzusatz. Eine fette, imperative Zeile behob es beim ersten Versuch: Specs müssen hier gespeichert werden, nicht dort, mit dem Default explizit als das zu vermeidende Ziel benannt.
Das Layout ist ein Ordner pro Squad (Checkout, Search, Accounts, Design-System), jeder mit eigenen Specs und Plänen. In einem Monorepo gehört die Zeile in die eigene CLAUDE.md des Packages. Claude Code lädt die Datei eines Unterverzeichnisses bei Bedarf, wenn es dort liest, und die Dokumentation sagt, der Owner jedes Verzeichnisses pflegt typischerweise dessen Datei. Entwickler, die das Plugin nie installiert haben, sind unbetroffen: Die Zeile greift nur, wenn ein Skill nach dem Speicherort fragt.
Dann lass die Plattform Ownership erzwingen. Eine CODEOWNERS-Zeile pro Squad-Ordner, und jedes Spec-Review landet bei den Leuten, die damit leben werden. Ein Vorbehalt: Der Override ist ein Prompt, keine Einstellung. Prüfe den ersten Spec nach jedem Plugin-Release.
Regel 2: privat versus geteilt
Regel 2: Nicht jeder Plan ist ein Team-Artefakt. Die erste Person, die Superpowers nach einem konfigurierbaren Speicherort fragte (Issue 337), formulierte es treffend: Plandateien können persönliche Arbeitsdokumente sein statt Projekt-Artefakte.
Für die private Seite gibt es eine eigene Datei. CLAUDE.local.md liegt neben der geteilten Datei, lädt nach ihr, und die Dokumentation sagt dir, sie selbst per Git zu ignorieren. Dein Redirect in einen privaten Ordner steht dort, und niemand sonst sieht ihn. Für den Ordner selbst gibt es eine Git-Ignore-Datei, die den geteilten Tree nie berührt: .git/info/exclude ist pro Clone, nie committet, und braucht keinen Pull Request. Das Plugin macht das für seinen eigenen Scratch-Bereich bereits selbst: Seit Version 6.0.3 legt sein Arbeitsverzeichnis eine .gitignore mit dem Inhalt * in sich selbst ab, sodass es sich ohne Eingriff in eine getrackte Datei selbst ignoriert.
Die geteilte Seite ist alles, was das Review-Gate durchlaufen hat, das der Brainstorm ohnehin ausführt: Spec geschrieben, Review angefragt, von einer zweiten Person freigegeben. Freigegeben, wandert er in den Squad-Ordner. Nicht freigegeben, bleibt er lokal. Beide werden auf einem Branch geschrieben, nie auf main. Zwei Zeilen in der geteilten CLAUDE.md reichen: Specs und Pläne als Start eines Features behandeln, und den Worktree anlegen, bevor sie geschrieben werden.
Eine Grenze: Ein git-ignorierter Plan reist nicht mit. Die Okama-Maintainer versuchten zunächst, den Ordner zu ignorieren, und machten es rückgängig, weil Pläne nicht mehr zwischen Maschinen und Agenten synchronisierten. Privat heißt privat.
Regel 3: ein Lebenszyklus, wie bei ADRs
Regel 3: Ein Spec hat einen Status, und ein toter Spec sagt das auch. Die Idee ist 15 Jahre alt. Michael Nygard schlug 2011 vor, Architecture Decision Records (ADRs) im Repository zu halten, eine durchnummerierte Datei pro Entscheidung. Eine Entscheidung wird proposed, dann accepted. Wenn ein späterer Record sie ändert, wird der alte deprecated oder superseded markiert, mit einer Referenz auf seinen Ersatz. Wird eine Entscheidung rückgängig gemacht, bleibt der alte Record erhalten, aber als superseded markiert.
Auf Specs angewendet, öffnet jeder geteilte Spec mit einem fünfzeiligen Header, den der Agent ohnehin liest:
| Feld | Zweck |
|---|---|
| status | proposed, accepted, superseded |
| superseded-by | der ersetzende Spec |
| owner | der Squad |
| touches | die Pfade, über die der Spec Aussagen macht |
| review date | wann er zuletzt geprüft wurde |
Editiere einen accepted Spec niemals zu einer anderen Entscheidung um. Schreib den nächsten, verweise zurück, und die Historie bleibt ehrlich. Eine Ausnahme, festgehalten in Anthropics Playbook: Wenn die Implementierung vom Plan abweicht, wird der Plan im selben Commit aktualisiert. Der Plan reist mit dem Diff, das ihn gebrochen hat, und ein Hook kann das erzwingen.
Spec Kit benennt drei Arten, wie ein Spec leben kann. Flow-forward: ein neuer Ordner pro Feature, alte bleiben als Historie erhalten. Living spec: der Spec ist der Contract, der Rest wird regeneriert. Flow-back: der Build formt den Spec zurück. Ihre Regel lautet, nichts in Tasks oder Code zu belassen, das etwas anderes sagt, als der Spec noch behauptet. Das ist eine bewusste Entscheidung für spec-anchored.
Die Grenze: Ein Status ist Metadaten, die ein Mensch setzt. Der Agent markiert seinen eigenen Spec nicht selbst als superseded, außer deine CLAUDE.md sagt es ihm, und selbst dann muss das Review es bemerken.
Regel 4: ein Drift-Gate in CI
Regel 4: Ein Spec, der über den Tree lügt, lässt den Build scheitern. Das Paper, das das Problem benannte, im Juni veröffentlicht, nennt es silent spec-code drift: Der Code entwickelt sich weiter, die Spezifikation nicht, und die Abweichung bleibt unsichtbar, bis sie teuer zu beheben ist. Seine Antwort ist ein Drift-Gate, eine blockierende Merge-Bedingung.
Der Check ist kleiner, als er klingt. Für jeden Spec, dessen Header accepted sagt, zieh die genannten Pfade, in Backticks oder in der touches-Zeile, und teste, ob jeder existiert. Fehlender Pfad, scheiternder Build, mit dem Namen des Specs im Log. Superseded- und proposed-Dateien werden übersprungen: Nur accepted Specs machen Aussagen über den Tree, also werden nur accepted Specs geprüft. TrueFoundry rahmt es als geplanten Diff statt Post-Incident-Archäologie: Ein Spec ist Scaffold, und eine Spec-Änderung ist eine Policy-Änderung.
Manche fahren die manuelle Variante schon. Ein Kommentator lässt Claude die Spec-Dateien mit der Codebase vergleichen und Tickets für das Fehlende anlegen. Das Skript macht das bei jedem Pull Request, kostenlos.
Der zweite Schutz ist der, den Okama eingeführt hat: den Ordner aus dem Docs-Build ausschließen. Eine Zeile in der Sphinx-Konfiguration hält die Dateien in Git, aber aus dem HTML draußen.
Die Grenze: Ein Pfad-Check fängt gelöschte Dateien, nicht geändertes Verhalten. Ein Spec kann jede existierende Datei nennen und trotzdem eine API beschreiben, die es nicht mehr gibt. Dafür sind Review und die Same-Commit-Regel da.
Regel 5: ein Größenbudget, und die Kosten
Regel 5: Die meisten Arbeiten verdienen keinen Spec. Die Belege zum Overhead von spec-driven development sind konsistent:
| Experiment | Ergebnis |
|---|---|
| Marmelab, Spec Kit an einem Feature, das das aktuelle Datum anzeigt | 8 Dateien, 1.300 Zeilen Spezifikationstext |
| OpenSpec-Bake-Off, gleiche Anforderungen mit Spec-Tool vs. Claude Code allein | 50% mehr Code, 50% mehr zyklomatische Komplexität, doppelt so lange, dreimal so teuer |
| Ein Team, das monatelang spec-driven development betreibt | 2 bis 3 mal so viele Tokens, etwa doppelt so lange, hoher Koordinationsaufwand für Änderungen, die keinen brauchten; kein Beleg, dass der Code besser wurde |
Der Bake-Off ist ein Experiment, kein Benchmark, und sein Autor sagt das selbst. Aber die Richtung stimmt. Also die Regel: Schreib einen Spec, wenn die Arbeit eine Squad-Grenze überschreitet oder in 90 Tagen erneut gelesen wird. Alles andere ist ein Prompt.
Superpowers sortiert jede Anfrage bereits in drei Pfade: spike, bounded, architectural. Nur der architectural-Pfad schreibt einen Spec. Halte den bounded-Pfad bounded, und halte den Spec nahe 300 Zeilen. Praktiker ergänzen zwei Zeilen: nicht zu groß specen, und die generierten Specs lesen.
Die Grenze wirkt in beide Richtungen. Derselbe Bake-Off fand drei Lücken, die der einfache Lauf verpasste. Der Spec kauft Coverage, nicht Geschwindigkeit. Zahl dafür, wo Coverage zählt.
Fazit: erst committen, dann regieren
Zurück zu den drei Fragen des Leads. Was versionieren wir: freigegebene Specs und Pläne, auf einem Branch, im Ordner des Squads. Drift: ein Status-Header und ein CI-Gate. Governance: Owners und eine Größenregel.
Fünf Regeln, und keine davon wird heute von einem Tool erzwungen. Das Override-Issue ist offen. Das Main-Branch-Issue ist offen. Der Pull Request, der die Anweisung umsortierte, wurde ohne Merge geschlossen. Das Team, das sich verbrannt hat, hielt an der Praxis fest: 8 Pläne und 6 Specs, committet, aus dem Docs-Build ausgeschlossen.
Böckelers Einwand bleibt bestehen. Mit Status-Header und Größenbudget liest du nur die accepted Specs, und weniger davon. Was du dafür bekommst, ist das, was Anthropics Playbook den Audit Trail nennt: wer was angefragt hat, was der Agent produziert hat, und wer es freigegeben hat.
Das ist Prozess, kein Tooling: eine CLAUDE.md-Datei, eine CODEOWNERS-Datei, ein Header und ein fünfzehnzeiliges Skript. Und wenn das Team eine CODEOWNERS-Anfrage nicht reviewen will, wird es auch keinen Spec reviewen. In diesem Fall war die .gitignore die ehrliche Wahl.
