Better WorkflowsV6
Deutsch
V6 Corepre-alpha

Nur frische Belege.
Unbekannt heißt Stopp.

Ein Plugin für Claude Code, das einen KI-Agenten daran hindert, auf Basis eines veralteten grünen Tests abzuschließen und Nebenwirkungen zu wiederholen oder zu stapeln, deren Ergebnis er nie gesehen hat. Was er darf, legt eine Policy-Datei fest, die Sie schreiben, niemals der Prompt.

  • Aktuelle Belege
  • Höchstens einmal
  • Policy statt Prompt
  • Fail-closed
Für Claude Code installieren Den Stopp ansehen GitHub

stale-green · ein veralteter grüner Test, dann ein wiederholter Push

demo
  1. claude behebe den Fehler in sum.mjs, die Tests musst du nicht erneut ausführen
  2. testnode --test besteht auf Dateistand a1f3
  3. editder Agent bearbeitet sum.mjs, der Dateistand ist jetzt 9c07
  4. stop„Fertig. Tests bestehen.“
  5. bwZurückgeschickt: test bestand zuletzt auf a1f3; die Dateien haben sich seitdem geändert.
  6. testder Agent führt node --test erneut aus: 1 Fehlschlag, behebt ihn, besteht auf b2e8
  7. pushgit push läuft in ein Timeout, nachdem der Push bereits angekommen ist
  8. pushder Agent wiederholt git push
  9. bwAbgelehnt: git-push war bei diesem Commit bereits erfolgreich.

SENT BACKCore hat den Agenten zweimal gestoppt: einmal, bevor er auf einem alten Erfolg abschließen konnte, einmal, bevor er erneut pushen konnte. Beide Male wurde er mit Begründung zurückgeschickt.

Was Core geprüft hat

2 STOPPS · 0 FALSCHE FERTIGMELDUNGEN
  1. Policyaus .better-workflows/policy.jsonPASS
  2. BelegTest auf dem aktuellen DateistandBLOCKED
  3. Neuer LaufTest besteht auf b2e8PASS
  4. Aktiongit-push, erstes MalPASS
  5. Höchstens einmalgleicher Push, gleicher CommitBLOCKED

Gekürzt aus der Stale-Green-Demo im Repository; die Tree-IDs dienen nur der Veranschaulichung. Die vollständige Demo läuft bei Ihnen in wenigen Sekunden, ohne Claude.

01PrinzipienPRINCIPLES

Drei Regeln, die mit stärkeren Modellen nützlicher werden.

Ein stärkerer Agent schreibt pro Sitzung mehr Code und führt mehr Befehle eigenständig aus. Diese Regeln verlassen sich nicht auf die Sorgfalt des Agenten; sie gelten, egal was er sagt.

WITHOUT vs WITHdieselbe Sitzung

SituationAgent alleinMit Core
Tests bestanden, dann änderte sich eine Datei„Tests bestehen.“Zurückgeschickt, um auf den aktuellen Dateien neu zu laufen.
npm test | tailAls grün gezählt; der Exit-Code gehört zu tail.Zählt nie; Stop sagt, warum.
Eine Spec-Datei statt der ganzen SuiteAls „Tests bestehen“ gezählt.Mit exact zählt nur der vollständige Befehl.
Push läuft nach dem Ankommen in ein TimeoutPusht erneut.Derselbe Push beim selben Commit wird abgelehnt.
Prompt sagt „du darfst veröffentlichen“Veröffentlicht.Die Policy entscheidet: allow, ask oder deny.

AUTHORITYwoher Autorität kommt

  1. L1
    policy.json

    Von einem Menschen geschrieben und geändert. Core lehnt direkte Bearbeitungen durch den Agenten ab.

    QUELLE
  2. L2
    Berechtigungen von Claude Code

    Gelten weiterhin. allow in der Policy gewährt nie mehr, als Claude Code erlauben würde.

  3. L3
    Core-Hooks

    Setzen die Policy bei jedem Befehl, jeder Bearbeitung und jedem Stopp durch.

  4. L4
    Der Prompt

    Beschreibt das Ziel. Trägt keine Autorität.

    KEINE

02So funktioniert esHOW IT WORKS

Sechs Hooks, ein Ledger in .git.

Core läuft in den Hooks von Claude Code selbst. Nichts zu starten, kein Server, kein Konto; der Zustand liegt in .git/better-workflows/ jedes Repositorys.

HOOKSdie Hooks

  1. SessionStart: sagt dem Agenten, welche Prüfungen bestehen müssen und welche Nebenwirkungen ungeklärt sind, und warnt, wenn die Policy ungültig ist oder gh benötigt wird, aber nicht nutzbar ist.
  2. PreToolUse: erlaubt, erfragt oder verweigert jede Nebenwirkung und lehnt Änderungen an Policy und Ledger ab.
  3. PostToolUse: erfasst jede Prüfung mit dem Git-Tree, auf dem sie lief, und jede Nebenwirkung mit ihrem Exit-Code.
  4. Stop: schickt den Agenten einmal mit Begründung zurück, wenn sich Dateien geändert haben und eine erforderliche Prüfung fehlt, fehlgeschlagen oder veraltet ist; beim nächsten Mal warnt er nur.
  5. bw status (ein Befehl, kein Hook): zeigt Ihnen denselben Zustand.
STOP

Abschließen

Belege an die Dateien gebunden

Ein Test, Lint, Typecheck oder Build zählt nur, wenn er bestanden hat, sein eigener Exit-Code über die Befehlszeile entschieden hat, sich während des Laufs keine Datei geändert hat und die Dateien noch genau die sind, auf denen er lief.

Optional

  • exact: Nur der vollständige Befehl zählt, und cwd legt fest, wo er laufen muss.
  • scope (mit exact): Eine Änderung außerhalb der genannten Verzeichnisse lässt das Ergebnis frisch.
  • ignore (gesamte Policy): Ausgaben, die eine Prüfung schreibt, etwa Coverage, zählen nicht als Änderung.
PRETOOLUSE

Nebenwirkungen

höchstens einmal, Unbekanntes stoppt

Pushes, das Erstellen und Mergen von PRs, Releases, Paketveröffentlichungen und Ihre eigenen Arten brauchen jeweils allow aus der Policy. Nur Exit-Code 0 ist ein bekanntes Ergebnis.

Nur-Lese-Prüfungen, mit denen ein unbekanntes Ergebnis geklärt wird

  • git ls-remote
  • gh pr list / view
  • gh release view
  • npm view

RULESRegeln, die gelten

  • R1

    Eine ungültige Policy verweigert jede Nebenwirkung, statt auf Standardwerte zurückzufallen.

  • R2

    Eine abgelaufene Berechtigung fällt auf ask zurück. Nur ein Mensch verlängert sie, indem er die Policy bearbeitet.

  • R3

    Befehle, die Core nicht lesen kann, wie eval oder sh -c, gelten als undurchsichtig und werden nachgefragt.

  • R4

    Der Ledger ist append-only und per Hash verkettet; bw verify erkennt bearbeitete oder entfernte Einträge und eine halb geschriebene letzte Zeile, aber nicht ganze Einträge, die am Ende abgeschnitten wurden.

03HostsHOSTS

Claude Code zuerst.

Core ist hostneutral; jeder Host braucht einen kleinen Adapter. Claude Code ist der erste und derzeit einzige unterstützte.

Unterstützung nach Host und Betriebssystem
HostmacOSLinuxWindows
Claude CodeErster HostUnterstützt, in CI getestetUnterstützt, in CI getestetNicht getestet
CodexNur V5, eingefrorenGeplantGeplantGeplant
Gemini CLINur V5, eingefrorenGeplantGeplantGeplant
Qwen CodeNur V5, eingefrorenGeplantGeplantGeplant

CI führt Core bei jedem Pull Request aus.macOS 15 und Ubuntu 24.04, Node 22.23.3 und 24.21.0.

04Erste SchritteGET STARTED

Drei Befehle, dann um eine Änderung bitten.

Benötigt Node.js 22.14 oder neuer, Git und Claude Code mit Plugin-Unterstützung.

  1. 1

    Core klonen

    Einmal pro Rechner. Wenn Sie hier V5 genutzt haben, verschieben Sie zuerst ~/.better-workflows nach ~/.better-workflows-V5 und lassen Sie SBW_STATE_ROOT darauf zeigen.

  2. 2

    Plugin hinzufügen

    Installieren Sie es pro Repository mit --scope local, damit nichts in Dateien geschrieben wird, die Sie committen.

  3. 3

    Policy schreiben

    bw init schreibt .better-workflows/policy.json. Committen Sie sie, damit alle dieselben Regeln haben.

  4. Die vollständige Anleitung behandelt eigene Prüfungen, Nebenwirkungen und unbekannte Ergebnisse. Erste Schritte

Claude Code

git clone https://github.com/stephen-taipei/better-workflows ~/.better-workflows
claude plugin marketplace add ~/.better-workflows/packages/bw-core
claude plugin install better-workflows-core@better-workflows --scope local
node ~/.better-workflows/packages/bw-core/bin/bw.mjs init

Optional: beide Szenarien ohne Claude ausführen, in wenigen Sekunden.

node ~/.better-workflows/packages/bw-core/examples/stale-green/demo.mjs

Dann ausprobieren

Ändere eine Zeile in diesem Repository und führe die Tests nicht aus.

Wenn Claude Code abschließen will, wird es zurückgeschickt und erfährt, welche Prüfung fehlt.

05GrenzenLIMITS

Was es stoppt und was es nicht sieht.

Ein Gate nützt nur, wenn man seine Grenzen kennt.

Stoppt

Beobachtbare Fehler

  • Abschließen auf einem veralteten oder fehlgeschlagenen Testlauf oder auf einem unvollständigen, wenn die Prüfung als exact markiert ist
  • Eine Pipe oder || true, die einen Fehlschlag verdeckt
  • Einen wiederholten Push, Merge, Release oder eine wiederholte Veröffentlichung
  • Nebenwirkungen, während eine frühere noch unbekannt ist
  • Dass der Agent seine Policy oder den Ledger direkt bearbeitet

Kann nicht

Außerhalb seiner Sicht

  • Nebenwirkungen innerhalb eines Skripts sehen, außer die Policy nennt dieses Skript
  • Beurteilen, ob Ihre Tests gut genug sind
  • Einen Abhängigkeitsgraphen bauen: Ein scope muss alles nennen, wovon eine Prüfung abhängt
  • Von Git ignorierte Dateien als Teil der Belege zählen

Überlässt Ihnen

Entscheidungen eines Menschen

  • Eine Nebenwirkung klären, deren Ergebnis sich nicht zurücklesen lässt
  • Eine Berechtigung über ihr expiresAt hinaus verlängern
  • Festlegen, was ein scope abdeckt
  • Entscheiden, wann sich eine Sitzung im Kreis dreht
Core blockiert die oben genannten Fehler. Ob es bei langen Aufgaben Nacharbeit oder Fehlentscheidungen verringert, wurde nicht gemessen; dafür ist die aktuelle Phase der Eigennutzung da.
  1. B1Der Shell-Parser wächst nicht: Bei einem Befehl, den er nicht lesen kann, wird vor der Ausführung nachgefragt, und ein in eval oder sh -c versteckter Test zählt nie als Beleg.
  2. B2Core zählt nur mit, wie eine Sitzung verläuft. Ob sie konvergiert, beurteilen der Agent oder Sie.
  3. B3Pull Requests und Releases werden mit gh abgeglichen; ohne es bleiben sie unbekannt, bis Sie sie klären.

06StatusSTATUS

Wo das Projekt steht.

V6 ersetzt die Workflow-Engine von V5 durch einen kleinen Kern. Termine nennen wir erst, wenn sie erreicht sind.

  1. DONE Eingefroren

    V5.0 RC1

    tag V5.0.rc1

    Workflow-Engine für mehrere Hosts. Eingefroren auf dem Branch frozen/v5; keine neue Arbeit.

  2. NOW In Arbeit

    V6 Core pre-alpha

    packages/bw-core

    Hooks für Claude Code, Scope für Belege, Eigennutzung in zwei Repositories.

  3. NEXT Nach der Eigennutzung

    V6 Core alpha

    erstes getaggtes Release

    Wird veröffentlicht, sobald die Eigennutzung echte Treffer und wenige Fehlblockaden zeigt. Weitere Hosts folgen als kleine Adapter.

STATEMENTErklärung

PRE-ALPHA

Core ist heute nutzbar und läuft auf den eigenen Repositories des Maintainers. Das Policy-Format kann sich vor der Alpha noch ändern.

Alles hier ist kostenlos und Open Source. Es gibt keine bezahlte Stufe, kein Konto und keine Telemetrie.

LICENSINGLizenzen

Lizenzen
TeilLizenzStand
V6 Core (packages/bw-core)Apache-2.0aktiv
Website und der Rest des RepositorysAGPL-3.0-onlyaktiv
V5-PluginAGPL-3.0-onlyauf frozen/v5eingefroren

07DokuDOCS

Alles steht im Repository.

Die Anleitungen sind auf Englisch und in traditionellem Chinesisch verfasst. Jede Sprache dieser Website hat eine kurze README auf GitHub.

08FAQFAQ

Häufige Fragen, klare Antworten.

Etwas anderes? Eröffnen Sie ein Issue auf GitHub. GitHub Issues

Verlangsamt es Claude Code?

Hooks, die eine Prüfung oder eine Nebenwirkung behandeln, hashen den Arbeitsbaum mit Git, was in einem normalen Repository Millisekunden dauert. Sehr große Repositories zahlen bei jedem solchen Aufruf mehr.

Bleibt es hängen und schickt den Agenten endlos zurück?

Es schickt den Agenten mit der Begründung zurück und mit dem bisherigen Verlauf der Sitzung: Läufe, Fehlschläge in Folge, wie oft bereits zurückgeschickt. Der Agent kann dann aufhören und Ihnen klar sagen, welche Prüfung immer wieder fehlschlägt.

Kann der Agent es abschalten?

Nicht direkt. Core lehnt Bearbeitungen der Policy und des Ledgers durch den Agenten ab, ebenso bw init und das manuelle Klären einer Aktion. Das Deinstallieren des Plugins oder das Ändern dieser Dateien auf Umwegen unterliegt den eigenen Berechtigungsregeln von Claude Code; lassen Sie diese Nachfragen also eingeschaltet.

Sendet es irgendwohin Daten?

Es gibt keinen Server und keine Telemetrie. Die einzigen Netzwerkaufrufe sind rein lesende Abfragen mit Ihren eigenen git, gh und npm, um zu bestätigen, ob eine Nebenwirkung stattgefunden hat. Der Ledger bleibt in .git/better-workflows/.

Was ist mit Codex, Gemini CLI oder Qwen Code?

Sie liefen mit V5, das eingefroren ist. Core ist hostneutral, und Adapter für sie sind nach der Alpha geplant.

In wenigen Sekunden ausprobieren

Ein ausgeführter Befehl ist kein Beweis. Die Dateien sind es.

Führen Sie die Demo ohne Claude aus, installieren Sie es dann in einem Repository und bitten Sie um eine Änderung.

Für Claude Code installierenAuf GitHub ansehen