Skip to content

Dokumentation: claude-workflow-kit ​

Das Kit macht aus Claude Code eine Werkstatt mit festem Ablauf: Eine Anforderung geht in acht Schritten bis in die Produktion. Die KI plant, schneidet Arbeitspakete, setzt um, prüft und lässt prüfen. Drei Entscheidungen bleiben bei dir. Diese Seite gibt den Überblick und zeigt, wo die Einzelheiten stehen.

Konzept ​

Das Kit besteht aus drei Teilen: einundzwanzig Skills, einer Config im Projekt und einem Installer. Es ist weder Plattform noch Agent.

Die Skills kennen kein bestimmtes Projekt. Build-Kommandos, Branch-Namen, Prüfungen und Review-Modell stehen in .claude/workflow.config.json. Verbessert sich ein Skill, gilt das nach dem nächsten Installer-Lauf in jedem Projekt, das das Kit nutzt.

Alle Zugriffe auf Issues und Board laufen über den Board-Adapter .claude/kit/board.mjs. Er spricht mit GitHub, GitLab oder einem lokalen Ordner issues/, und die Skills merken davon nichts.

Wo was steht:

  • Einrichtung: Installation, Config, Issue-Tracker, Aktualisieren.
  • Der Prozess: die acht Schritte, jeder Skill mit Zweck und Folgeschritt, ein ganzer Durchlauf.
  • Runner: Arbeitspakete ohne Aufsicht umsetzen lassen.
  • Einstellungen: jede Einstellung mit Wirkung und Vorgabe.

Voraussetzungen ​

Das Kit läuft unter macOS, Linux oder Windows über WSL2; die Einrichtung unter Windows beschreibt die Anleitung Windows über WSL2. Welche Werkzeuge und Zugänge du brauchst, nennt der Einstieg; Board-Spalten und Tracker-CLI für GitHub oder GitLab stehen unter Issue-Tracker und Code-Host.

Optional ist ein Vault für Notizen über Sitzungen hinweg; /session-start und /document laufen auch ohne ihn. Die Datei dazu beschreibt kontext.config.json.

Die acht Schritte ​

SchrittWasWerSkill
1Anforderung formulierenMensch–
2PlanenKI/techplan
3Arbeitspakete anlegenKI/issues
4GO: Pakete nach Ready ziehenMensch–
5UmsetzenKI/implement-ready
6Review durch ein zweites ModellKI/kit-review
7Push auf mainMensch/push-main
8Merge nach productionMensch/merge-production

Weitere Skills bereiten den Ablauf vor oder gliedern ihn, siehe Die Skills.

Drei Bahnen ​

Nicht jede Aufgabe braucht alle acht Schritte. Das Kit kennt drei Bahnen.

Bahn 1 — Kleine Änderung. Eine Datei, ein Asset oder ein Config-Wert, ohne Migration, Endpoint, Datenmodell oder sicherheitsrelevante Logik und höchstens ein Modul. Die KI setzt direkt um und committet; Plan, Arbeitspaket und GO entfallen. Auch hier verlangt das Commit-Gate einen grünen node .claude/kit/checks.mjs run.

Bahn 2 — Feature. Der volle Ablauf: /techplan, /issues, GO, /implement-ready. Typisch sind ein Datenmodell mit mehreren vertretbaren Schnitten oder ein Endpoint, dessen Vertrag offen ist.

Bahn 3 — [Task]. Mehr als eine Kleinigkeit, aber nichts abzuwägen. /task legt nach deiner Bestätigung genau ein Arbeitspaket mit dem Präfix [Task] an, ohne Fachplan, Plan und Zerlegung. Typisch sind eine Umbenennung über viele Dateien oder eine mechanische Nacharbeit.

Die Auswahl folgt drei Regeln, in dieser Reihenfolge:

  1. Passt die Aufgabe zu Bahn 1 und gibt es nichts abzuwägen, gilt Bahn 1.
  2. Sonst entscheidet, ob mehrere vertretbare Wege offenstehen: Dann gilt Bahn 2, sonst Bahn 3.
  3. Ist das unklar, gilt Bahn 2.

Die Zahl der Dateien entscheidet also nicht: Zwölf Dateien ohne Abwägung sind Bahn 3, eine einzige Datei mit zwei vertretbaren Schnitten ist Bahn 2. Vor jeder Aufgabe nennt die KI ihre Bahn.

Die drei menschlichen Stop-Punkte ​

Das GO (Schritt 4). Du ziehst die Arbeitspakete nach Ready und legst damit fest, was als Nächstes gebaut wird, in welcher Reihenfolge und wie viel auf einmal. Für den Runner kannst du das GO vorab geben: Kennzeichnest du eine fachliche Anforderung oder einen Plan mit dem Label aus night.chain.variantBLabel, zieht die Kette die daraus geschnittenen Pakete selbst nach Ready und setzt sie um.

Der Push (Schritt 7). Erst push main bringt die Commits auf den Test-Server. Jeder Push braucht deine eigene Freigabe; davor kannst du den Umfang noch ändern oder verwerfen, auch die Entscheidungen, die ein Lauf getroffen hat.

Der Merge (Schritt 8). Nach deiner Prüfung auf dem Test-Server bringt merge production den Stand in die Produktion.

Hotfix und Zurückkehren. hotfix production liefert den Fix genau einer freigegebenen Karte aus und ersetzt für ihn Push und Merge. rollback production holt die Vorversion zurück. Nur mit Pro.

Diese drei Schritte automatisiert das Kit absichtlich nicht. Die KI erledigt die Arbeit, entscheiden tust du.

Leitplanken statt Prompts ​

Ein Modell schreibt, was in seinen Trainingsdaten am häufigsten vorkommt, also oft eine abgekündigte API oder ein veraltetes Idiom. Eine Bitte im Prompt hilft dagegen wenig. Das Kit setzt auf Prüfungen, die im Pflicht-Gate scheitern: eine Lint- oder Compiler-Regel in den buildChecks, die aus vorhandenen Annotationen ableitet, etwa @typescript-eslint/no-deprecated oder Java mit -Xlint:deprecation und -Werror. Welche Regeln gelten, legt jedes Projekt in seiner Config fest.

Dasselbe Prinzip gilt für die Anweisungen des Kits, mit dem Maßstab „Regel im Text oder Regel im Werkzeug“: Was sich an Ausgabe oder Ergebnis prüfen lässt, prüft ein Kommando; im Text bleibt nur, was ein Urteil im Einzelfall verlangt. Wo sich nichts messen lässt, verlangt das Kit eine feste Antwortform, die einen Verstoß sichtbar macht, siehe Mitteilungen: glauben statt nachsehen.

Auch was der Mensch zu Beginn einer Sitzung wissen muss, steht nicht als Bitte im Text: Der Hook SessionStart ruft node .claude/kit/board.mjs hook session-start und zeigt, wie es um die Prüfung der fertigen Karten steht. Der Installer trägt ihn ein, siehe Einrichtung.

Was bewusst nicht im Kit ist ​

Security-Gates. Secrets, SQL-Konkatenation und fehlende Eingabeprüfung finden Werkzeuge wie gitleaks, Semgrep oder SpotBugs im CI zuverlässiger als ein Modell. Das Review des Kits ergänzt sie.

Andere KI-Werkzeuge. Die Skills sind für Claude Code geschrieben. Codex liest AGENTS.md, Cursor .cursor/rules; wer mehrere Werkzeuge einsetzt, pflegt die Anweisungen in deren Formaten selbst.

Namen für Umsteiger von Version 4 ​

Version 5 benennt Skills, Kommandos, Optionen, Werte, Präfixe und Labels englisch.

Skills ​

Ein alter Name wird abgewiesen, und die Meldung nennt den neuen.

AltNeu
/kontext, /context/session-start
/fachplan/requirement
/review/kit-review
/plan (Wegweiser)entfällt, der Planungsschritt ist /techplan

/hotfix-production und /rollback-production sind neu und haben keinen Altnamen.

Kommando-Dateien ​

AltNeu
kit/befunde.mjskit/findings.mjs
kit/aufwand.mjskit/effort.mjs
kit/wirksamkeit.mjskit/effectiveness.mjs
einstellungen.mjssettings.mjs

Befehle ​

KommandoAltNeu
kit/board.mjskontext, sitzungcontext, session
kit/board.mjsissue melden, nightrun melden, sitzung meldenissue report, nightrun report, session report
kit/board.mjsissue stand, issue auftrag, issue ursprungissue run-state, issue brief, issue origin
kit/board.mjsissue check-geschuetzt, issue vorgeschichte, issue fragenissue check-protected, issue history, issue questions
kit/board.mjsissue-review pruefauftragissue-review review-brief
kit/board.mjshook bash-pruefenhook bash-check
kit/board.mjscode schutz mit einrichten, aussetzen, wiederherstellen, nachpruefencode protection mit setup, suspend, restore, verify
kit/checks.mjsbereicheareas
kit/findings.mjsarten, pruefen, buchen, vorschlag, auswerten, befundkinds, check, record, suggest, evaluate, finding
kit/effort.mjsauswerten, befund, auskunftevaluate, finding, info
kit/effectiveness.mjsauswerten, befund, kandidatenevaluate, finding, candidates
kit/worktree.mjsanlegen, entfernen, im, nachziehen-pruefen, rueckwegcreate, remove, in, catch-up-check, return
kit/worktree.mjsvorbereitung-festhalten, vorbereitung-pruefenrecord-preparation, check-preparation

Optionen ​

KommandoAltNeu
kit/board.mjs--teil, --zustand, --spalte, --pfad, --zweig, --nur-pfad--part, --state, --column, --path, --branch, --path-only
kit/board.mjs--stufe, --rolle, --datei, --material-datei, --auftrag, --ausgabe, --protokoll--stage, --role, --file, --material-file, --brief, --output, --transcript
kit/board.mjs--begriffe, --dateien, --ohne, --vergleich--terms, --files, --without, --compare
kit/checks.mjs--stufe, --bereich, --abschluss, --frisch, --wiederholen--stage, --area, --finish, --fresh, --retry
kit/night.mjs--kette, --pruefen, --waechter--chain, --check, --watcher
kit/findings.mjs--datei, --stufe, --karte, --art, --abgelehnt--file, --stage, --card, --kind, --rejected
kit/effort.mjs--laeufe--runs
kit/effectiveness.mjs--fenster--window
kit/worktree.mjs--praefix, --ergebnis, --offen, --verwerfen--prefix, --result, --open, --discard
install.mjs--sprache, --schutz--language, --protection, --reconfigure

Auswahlwerte ​

StelleAltNeu
kit/board.mjs --artfachlich, idee, menschrequirement, idea, human
kit/board.mjs --statelaeuft, abgebrochen, wartet, fertigrunning, aborted, waiting, done
kit/board.mjs --stagefachlichrequirement
kit/checks.mjs --stagepaketpackage
kit/findings.mjs --stagefachlichrequirement
kit/worktree.mjs --resultgruen, gruen-offen, rotgreen, green-open, red
kit/worktree.mjs --fetchfehlgeschlagenfailed
/push-mainvorbereiten, notfallprepare, emergency

Titel-Präfixe ​

Neue Karten tragen die englischen, die deutschen erkennt das Kit an offenen Karten weiter.

AltNeu
[Fachlich][Requirement]
[Idee][Idea]
[Mensch][Human]

Labels ​

Das Kit setzt die englischen, erkennt die deutschen an offenen Karten und räumt sie ab, wo es das englische abräumen würde.

AltNeu
kit:klaerenkit:clarify
kit:geschuetztkit:protected
kit:durchziehenkit:carry-through
kit:pruefenkit:check
lauf:laeuftrun:running
lauf:abgebrochenrun:aborted
lauf:wartetrun:waiting
review:fertigreview:done
ziel:plangoal:plan
ziel:paketegoal:packages
ziel:umsetzunggoal:implementation
ziel:push-vorbereitetgoal:push-prepared

kit:on-hold ist neu und hat keinen deutschen Altnamen. Es zeigt am Board, dass eine fachliche Anforderung auf ein äußeres Ereignis wartet; maßgeblich ist die Zeile Wartet auf Ereignis: <Grund> im Abschnitt ## Ziel. Beides setzt node .claude/kit/board.mjs issue hold <N> --reason "<Grund>", beides hebt issue hold <N> --lift auf, siehe Warten auf ein Ereignis.

Lizenz ​

Community und Pro: siehe Lizenz.

claude-workflow-kit — frei verfügbar