zfdw-ki-leitplanken
Eine Arbeitsweise für Projekte, in denen ein KI-Assistent mitbaut. Kein Framework, keine
Installation — elf Methoden-Dokumente, vier Vorlagen, vier Slash-Commands, zwei Hooks und ein
Prüfskript, die man einzeln übernehmen kann. Einzige Voraussetzung: Der Guard braucht bash,
git und jq; fehlt jq, blockt er (fail-closed) — siehe hooks/README.md.
| |
|---|
| Version | v0.3.0 |
| Werkzeug | geschrieben für Claude Code; der Guard läuft unverändert auch unter Codex und als git pre-commit-Hook für jeden anderen Assistenten — siehe Mit anderen Assistenten |
| Sprache | Deutsch |
| Lizenz | Apache-2.0 — frei nutzbar, auch kommerziell |
| Herausgeber | Wirkarchitektur · sitelook GmbH, Neuss — wirkarchitektur.de |
Wofür das gut ist
Ein KI-Assistent, der Code schreibt, ist nach zwei Wochen produktiver Nutzung an denselben vier
Stellen unzuverlässig:
- Er vergisst das Vorhaben. Was im Chat-Verlauf steht, ist nach einem Kontext-Reset weg.
- Er baut mehr, als vereinbart war. Aus „Login reparieren" wird ein Umbau der Navigation.
- Er hält sich nicht an Regeln, die nur als Text existieren. Nicht aus Ungehorsam — die Regel
konkurriert mit 600 anderen Zeilen im Kontext.
- Er meldet „fertig", wo „ungeprüft" richtig wäre. Ein Statuscode 200 beweist nichts, ein
Prüfskript ohne Voraussetzung meldet Grün.
Alle vier sind lösbar, und zwar mit Dateien im Repo statt mit Disziplin. Genau das steht hier.
Der Kern in fünf Sätzen
- Arbeit, die größer ist als ein Commit, bekommt eine Sprint-Datei — und diese Datei ist
zugleich der Stand, nicht bloß ihre Beschreibung.
- Jede Datei, die ein Sprint schreiben darf, steht in seinem Write-Scope. Wer außerhalb
schreiben will, hält an.
- Jede Regel hat einen richtigen Ort: Anweisungsdatei, Hook, Skill oder Command — und am
falschen Ort wirkt sie nicht.
- Was nie passieren darf, gehört in einen Hook. Ein Text ist ein Vorschlag an ein Sprachmodell.
- Wer einen Schritt auslässt, nennt ihn vorher. Ein unprotokollierter Skip ist von einer
übersehenen Lücke nicht zu unterscheiden.
Einordnung
Spec-driven Development kennt drei Reifegrade: Spec-first — einmal vor der Arbeit spezifiziert,
danach liegt das Dokument still. Spec-anchored — die Spezifikation wird mitgeführt und beim
Abschluss fortgeschrieben. Spec-as-Source — Menschen editieren nur noch die Spezifikation, nie
den Code.
Diese Sammlung ist Spec-anchored, und das ist eine Entscheidung, keine Zwischenstufe. Spec-first
scheitert daran, dass das Dokument nach dem dritten Tag nicht mehr stimmt und niemand es merkt.
Spec-as-Source setzt voraus, dass generierter Code nie von Hand angefasst wird — eine Annahme, die
in gewachsenen Kundenprojekten nicht trägt. Hier ist die Sprint-Datei der Stand selbst, nicht dessen
Ankündigung: Sie wird beim Abschluss um das tatsächliche Ergebnis ergänzt und bleibt als
Begründungsspur zum Diff liegen.
Was das gegenüber SpecKit, BMAD, OpenSpec, GSD und Kiro bedeutet — und wann eines der fünf die
bessere Wahl ist —, steht in 07 — Verortung.
Was drin ist
methode/ die elf Dokumente — das Warum
vorlagen/ PLAN.md, Sprint-Datei, Anweisungsdatei, Entscheidung — das Was
commands/ /sprint-planen · /sprint-starten · /sprint-abschliessen · /review-aenderungen
hooks/ Guard gegen geschützte Daten + Turn-Ende-Signal, mit Testsuite und Rot-Beweis
werkzeuge/ Herkunfts-Gate: prüft vor einer Veröffentlichung auf Kundenbezug
Anfangen — der kleinste sinnvolle Schritt
Nicht alles auf einmal. Die Reihenfolge, die sich bewährt hat:
1. Der Guard, bevor irgendetwas anderes — als Paar mit dem pre-commit-Hook. Er ist der einzige
Teil, dessen Fehlen echten Schaden anrichten kann:
mkdir -p .claude/hooks
cp hooks/guard-geschuetzte-daten.sh hooks/stop-git-status.sh .claude/hooks/
chmod +x .claude/hooks/*.sh
cp hooks/settings.json.vorlage .claude/settings.json
cp hooks/geschuetzte-pfade.vorlage .claude/geschuetzte-pfade
cp hooks/pre-commit.vorlage .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
hooks/tests/test-guard.sh
hooks/tests/rot-beweis.sh # zeigt, dass die Suite einen kaputten Guard bemerkt
Beide gehören zusammen. Der Werkzeug-Guard prüft den Befehl des Assistenten: Er blockt
git add und git commit -a, die eine geschützte Datei erfassen würden. Ein schlichtes
git commit -m … über eine Datei, die schon im Index liegt, lässt er durch — das fängt erst der
pre-commit-Hook, der den Index prüft. Beide sind lokal und mit git commit --no-verify bzw.
an der Shell des Assistenten vorbei umgehbar. Die Schicht darüber liegt auf dem Server:
Secret-Scanning mit Push-Schutz und verpflichtende Statuschecks vor dem Merge. Zusammen senken die
drei das Risiko; eine Sperre gegen jeden Datenabfluss ist keine davon
(siehe hooks/README.md).
Dann die Schutzmuster auf dein Projekt setzen. Die Vorgaben decken Secrets ab, nicht deine
Kundendaten.
2. Die Anweisungsdatei kürzen. Vorlage nach CLAUDE.md, Richtwert 200 Zeilen. Was rausfliegt,
wandert in einen Skill und hinterlässt einen Anker.
3. Der erste Sprint. Beim nächsten Vorhaben, das größer ist als ein Commit:
mkdir -p docs/plan
cp vorlagen/PLAN.md vorlagen/sprint-NN.md docs/plan/
cp commands/*.md .claude/commands/
Dann /sprint-planen <dein Vorhaben>.
4. Alles andere später. Wer mit allen vier Schritten gleichzeitig anfängt, hört nach dem zweiten
auf.
Wenn du selbst aus Kundenarbeit destillierst: vor der ersten Veröffentlichung
06 — Herkunft und Weitergabe lesen und das Gate scharf
stellen:
cp werkzeuge/herkunft-begriffe.vorlage .herkunft-begriffe # auf die eigenen Kunden setzen
werkzeuge/herkunft-check.sh
Mit anderen Assistenten
Die Methode steckt in Dateien, nicht im Modell — Sprint-Datei, Write-Scope, Entscheidungsvorlage,
Prüflisten, Rot-Beweis und Herkunfts-Gate funktionieren mit jedem Assistenten, der Dateien liest
und schreibt. Werkzeugabhängig sind nur die Stellen, an denen sich das Werkzeug einhängen lässt:
| Baustein | Claude Code | Codex | Cursor, Copilot u. a. |
|---|
| Anweisungsdatei | CLAUDE.md | AGENTS.md — Inhalt der Vorlage 1:1 übertragbar | AGENTS.md wird von den meisten gelesen |
| Guard vor dem Befehl | PreToolUse in .claude/settings.json | PreToolUse in .codex/hooks.json — gleiches Eingabeformat, gleicher Exit-Code, derselbe Guard ohne Änderung | — |
| Guard vor dem Commit | hooks/pre-commit.vorlage → .git/hooks/pre-commit | ebenso | ebenso — greift bei jedem, der committet |
| Slash-Commands | .claude/commands/ | als Prompt-Datei verwendbar | als Prompt-Datei verwendbar |
| Ausgang sperren (10) | permissions deny/ask | Sandbox- und Freigabestufen | je nach Werkzeug |
Codex:
mkdir -p .codex/hooks
cp hooks/guard-geschuetzte-daten.sh .codex/hooks/ && chmod +x .codex/hooks/*.sh
cp hooks/codex-hooks.json.vorlage .codex/hooks.json
cp hooks/geschuetzte-pfade.vorlage .codex/geschuetzte-pfade
Die Vorlage ruft den Guard über git rev-parse --show-toplevel auf, nicht über einen relativen
Pfad: Codex startet Hooks im Arbeitsverzeichnis der Sitzung, und ein Hook, der nicht gefunden wird,
gilt dort als fehlgeschlagen — der Befehl läuft trotzdem. Live geprüft mit codex-cli 0.154.0:
Aus einem Unterordner gestartet, blockt der Guard git add -A neben einer .env. Zweite Falle:
Hooks aus .codex/hooks.json lädt Codex nur, wenn das Projekt als vertrauenswürdig eingestuft
ist (laut Codex-Doku); sonst ist der Guard dort schlicht nicht aktiv.
Jeder andere Assistent — und jeder Mensch: den Guard ablegen (.claude/hooks/,
.codex/hooks/ oder .githooks/) und den pre-commit-Hook einhängen:
cp hooks/pre-commit.vorlage .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
Der pre-commit-Hook prüft den Index statt eines Befehls (guard-geschuetzte-daten.sh --staged)
und greift damit unabhängig davon, wer committet. Er ist mit git commit --no-verify umgehbar —
deshalb ergänzt er den Werkzeug-Hook, statt ihn zu ersetzen: Der eine greift vor dem Befehl, der
andere, bevor etwas Geschichte wird.
Woher das kommt
Wirkarchitektur heißt: Strukturen bauen,
die tatsächlich etwas bewirken — nicht solche, die im Dokument richtig aussehen. Diese Sammlung ist
die Arbeitsweise dahinter, und sie ist entlang derselben Frage geschnitten: wirkt die Regel dort,
wo sie steht? Eine Vorschrift in einer 600-Zeilen-Datei wirkt nicht. Ein Guard, der die Wirkung
eines Befehls prüft, wirkt.
Der Stoff kommt aus der Praxis eines Ein-Personen-Beratungsbetriebs, der Kundensoftware mit
KI-Unterstützung baut — also aus Projekten, in denen es keine zweite Person gibt, die den Fehler bemerkt, und kein Team,
das Prozess-Disziplin erzwingt. Deshalb der Zuschnitt: so wenig Zeremonie wie möglich, aber die
harten Grenzen in Code.
Die Sprint-Vorlage kommt aus Kundenarbeit in geregelten Umgebungen — dort, wo Belege
nicht optional sind, weil Informationssicherheits-Assessments, Datenschutz-Nachweise und
Kundenaudits danach fragen. Ihre Abschnitte sind entlang der Fragen geschnitten, die in
solchen Prüfungen tatsächlich gestellt werden: Welche Daten? Wer durfte schreiben? Welche
Zugänge, wie lange? Wer hat freigegeben? Was wurde ausgelassen — und wer hat das Restrisiko
abgenommen?
Der Grundgedanke „ein Arbeitsabschnitt = eine Datei, die zugleich der Zustand ist" ist
angeregt durch die Plan-First-Orchestrierung von
CC_GodMode (Dennis Westermann) — dort
eingebettet in ein umfangreiches Agenten-System mit eigener Toolchain. Umsetzung, Schnitt
und Nachweislogik hier sind eigenständig: kein Zustandsschema, kein Agenten-Ensemble, keine
Laufzeit. Die Datei im Repo ist der Zustand.
Mitmachen
Verbesserungen gern als Pull-Request, Kritik als Issue. Was hier steht, ist bewusst schmal und
begründet — ein Vorschlag wird eher aufgenommen, wenn er einen konkreten Fehlschlag beschreibt, den
er verhindert hätte. Siehe CONTRIBUTING.md.
Was das hier nicht ist
- Kein Compliance-Framework. „Leitplanken" meint hier Entwicklungspraxis, nicht EU AI Act,
Risikoklassen oder Nutzungsrichtlinien fürs Unternehmen. Wer das sucht, ist im falschen Repo.
- Kein Agenten-Framework. Es installiert nichts und startet nichts.
- Kein Ersatz für Code-Review. Es sorgt dafür, dass es etwas Prüfbares gibt.
- Keine Garantie. Apache-2.0, ohne Gewährleistung — wie jede Methode gilt sie, bis sie in deinem
Projekt nicht mehr gilt. Dann gehört sie angepasst, nicht befolgt.
