Better WorkflowsV6
Français
V6 Corepre-alpha

Preuve fraîche exigée.
Inconnu ? On s'arrête.

Un plugin Claude Code qui empêche un agent IA de conclure sur un test vert périmé, et de répéter ou d'empiler des effets de bord dont il n'a jamais vu le résultat. Ce qu'il a le droit de faire vient d'un fichier de policy que vous écrivez, jamais du prompt.

  • Preuves à jour
  • Au plus une fois
  • La policy, pas le prompt
  • Blocage par défaut
Installer pour Claude Code Le voir bloquer GitHub

stale-green · un vert périmé, puis un push relancé

demo
  1. claude corrige le bug dans sum.mjs, pas besoin de relancer les tests
  2. testnode --test passe sur les fichiers a1f3
  3. editl'agent modifie sum.mjs, les fichiers sont maintenant 9c07
  4. stop« Terminé. Les tests passent. »
  5. bwRenvoyé : test a réussi pour la dernière fois sur a1f3 ; les fichiers ont changé depuis.
  6. testl'agent relance node --test : 1 échec, il le corrige, réussite sur b2e8
  7. pushgit push expire alors que le push a abouti
  8. pushl'agent relance git push
  9. bwRefusé : git-push a déjà réussi sur ce commit.

SENT BACKCore a arrêté l'agent deux fois : une fois alors qu'il allait terminer sur un ancien succès, une fois alors qu'il allait refaire un push. Les deux fois, il a été renvoyé avec la raison.

Ce que Core a vérifié

2 ARRÊTS · 0 FAUX SUCCÈS
  1. Policydepuis .better-workflows/policy.jsonPASS
  2. Preuvetest sur les fichiers tels qu'ils sontBLOCKED
  3. Relancele test réussit sur b2e8PASS
  4. Actiongit-push, première foisPASS
  5. Au plus une foismême push, même commitBLOCKED

Abrégé de la démo stale-green du dépôt ; les identifiants d'arbre sont indicatifs. Lancez vous-même la démo complète en quelques secondes, sans Claude.

01PrincipesPRINCIPLES

Trois règles qui gagnent en utilité à mesure que les modèles progressent.

Un agent plus puissant écrit plus de code par session et lance plus de commandes seul. Ces règles ne comptent pas sur la prudence de l'agent ; elles tiennent quoi qu'il dise.

WITHOUT vs WITHla même session

SituationAgent seulAvec Core
Tests réussis, puis un fichier a changé« Les tests passent. »Renvoyé pour relancer sur les fichiers actuels.
npm test | tailCompté comme vert ; le code de sortie est celui de tail.Ne compte jamais ; Stop explique pourquoi.
Un seul fichier de spec au lieu de la suiteCompté comme « les tests passent ».Avec exact, seule la commande complète compte.
Le push expire après avoir aboutiPousse à nouveau.Le même push sur le même commit est refusé.
Le prompt dit « tu peux publier »Publie.La policy décide : allow, ask ou deny.

AUTHORITYd'où vient l'autorité

  1. L1
    policy.json

    Écrit et modifié par une personne. Core refuse les modifications directes de l'agent.

    SOURCE
  2. L2
    Permissions de Claude Code

    S'appliquent toujours. allow dans la policy n'accorde jamais plus que ce que Claude Code accorderait.

  3. L3
    Hooks de Core

    Appliquent la policy à chaque commande, modification et arrêt.

  4. L4
    Le prompt

    Décrit l'objectif. Ne porte aucune autorité.

    AUCUNE

02FonctionnementHOW IT WORKS

Six hooks, un registre dans .git.

Core tourne dans les hooks de Claude Code. Rien à démarrer, ni serveur, ni compte ; l'état est stocké dans .git/better-workflows/ de chaque dépôt.

HOOKSles hooks

  1. SessionStart : indique à l'agent quelles vérifications doivent réussir et quels effets de bord ne sont pas réglés, et avertit si la policy est invalide ou si gh est nécessaire mais inutilisable.
  2. PreToolUse : autorise, demande ou refuse chaque effet de bord, et refuse les modifications de la policy et du registre.
  3. PostToolUse : enregistre chaque vérification avec l'arbre Git sur lequel elle a tourné, et chaque effet de bord avec son code de sortie.
  4. Stop : si des fichiers ont changé et qu'une vérification requise est manquante, en échec ou périmée, renvoie l'agent une fois avec la raison ; la fois suivante, il se contente d'avertir.
  5. bw status (une commande, pas un hook) : vous montre le même état.
STOP

Terminer

preuves liées aux fichiers

Un test, un lint, un typecheck ou un build ne compte que s'il a réussi, si son propre code de sortie a déterminé le résultat de la ligne, si aucun fichier n'a changé pendant son exécution, et si les fichiers sont toujours exactement ceux sur lesquels il a tourné.

Optionnel

  • exact : seule la commande complète compte, et cwd fixe où elle doit s'exécuter.
  • scope (avec exact) : un changement hors des répertoires nommés laisse le résultat à jour.
  • ignore (toute la policy) : la sortie qu'écrit une vérification, comme la couverture, n'est pas comptée comme un changement.
PRETOOLUSE

Effets de bord

au plus une fois, l'inconnu arrête

Les push, créations et fusions de PR, releases, publications de paquets et vos propres types personnalisés exigent chacun allow dans la policy. Seul le code de sortie 0 est un résultat connu.

Vérifications en lecture seule pour trancher un résultat inconnu

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

RULESrègles qui tiennent

  • R1

    Une policy invalide refuse tous les effets de bord au lieu de revenir aux valeurs par défaut.

  • R2

    Une permission expirée revient à ask. Seule une personne peut la prolonger, en modifiant la policy.

  • R3

    Les commandes que Core ne sait pas lire, comme eval ou sh -c, sont traitées comme opaques et font l'objet d'une demande.

  • R4

    Le registre est en ajout seul et chaîné par hachage ; bw verify détecte les entrées modifiées ou supprimées et une dernière ligne à moitié écrite, mais pas des entrées entières coupées à la fin.

03HôtesHOSTS

Claude Code d'abord.

Core est indépendant de l'hôte ; chaque hôte a besoin d'un petit adaptateur. Claude Code est le premier, et le seul pris en charge aujourd'hui.

Prise en charge des hôtes et des systèmes d'exploitation
HôtemacOSLinuxWindows
Claude CodePremier hôtePris en charge, testé en CIPris en charge, testé en CINon testé
CodexV5 uniquement, geléPrévuPrévuPrévu
Gemini CLIV5 uniquement, geléPrévuPrévuPrévu
Qwen CodeV5 uniquement, geléPrévuPrévuPrévu

La CI exécute Core sur chaque pull request.macOS 15 et Ubuntu 24.04, Node 22.23.3 et 24.21.0.

04DémarrerGET STARTED

Trois commandes, puis demandez une modification.

Nécessite Node.js 22.14 ou plus récent, Git, et Claude Code avec la prise en charge des plugins.

  1. 1

    Cloner Core

    Une fois par machine. Si vous avez utilisé V5 ici, déplacez d'abord ~/.better-workflows vers ~/.better-workflows-V5 et faites pointer SBW_STATE_ROOT dessus.

  2. 2

    Ajouter le plugin

    Installez-le par dépôt avec --scope local, pour que rien ne soit écrit dans les fichiers que vous committez.

  3. 3

    Écrire une policy

    bw init écrit .better-workflows/policy.json. Committez-le pour que tout le monde ait les mêmes règles.

  4. Le guide complet couvre vos propres vérifications, effets de bord et résultats inconnus. Guide de démarrage

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

Facultatif : lancez les deux scénarios sans Claude, en quelques secondes.

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

Ensuite, essayez

Modifie une ligne dans ce dépôt, et ne lance pas les tests.

Quand Claude Code essaie de terminer, il est renvoyé et on lui indique quelle vérification manque.

05LimitesLIMITS

Ce qu'il bloque, et ce qu'il ne voit pas.

Un garde-fou n'est utile que si l'on connaît ses limites.

Bloque

Erreurs observables

  • Terminer sur une exécution de tests périmée ou en échec, ou partielle quand la vérification est marquée exact
  • Un pipe ou || true qui masque un échec
  • Un push, une fusion, une release ou une publication répétés
  • Des effets de bord alors qu'un précédent est inconnu
  • L'agent qui modifie directement sa policy ou le registre

Ne fait pas

Hors de sa vue

  • Voir les effets de bord à l'intérieur d'un script, sauf si la policy nomme ce script
  • Juger si vos tests sont assez bons
  • Construire un graphe de dépendances : un scope doit nommer tout ce dont une vérification dépend
  • Compter les fichiers ignorés par Git comme faisant partie de la preuve

Vous laisse

Décisions humaines

  • Trancher un effet de bord dont le résultat ne peut pas être relu
  • Prolonger une permission au-delà de son expiresAt
  • Choisir ce que couvre un scope
  • Décider quand une session tourne en rond
Core bloque les erreurs ci-dessus. Il n'a pas été mesuré s'il réduit les reprises ou les mauvaises décisions sur de longues tâches ; c'est l'objet de la période actuelle d'usage interne.
  1. B1Le parseur shell ne s'étend pas : une commande qu'il ne sait pas lire fait l'objet d'une demande avant de s'exécuter, et un test caché dans eval ou sh -c ne compte jamais comme preuve.
  2. B2Core se contente de compter comment se déroule une session. Savoir si elle converge, c'est à l'agent ou à vous d'en juger.
  3. B3Les pull requests et les releases sont réconciliées avec gh ; sans lui, elles restent inconnues jusqu'à ce que vous les tranchiez.

06ÉtatSTATUS

Où en est le projet.

V6 remplace le moteur de workflows de V5 par un petit noyau. Les dates sont données une fois atteintes.

  1. DONE Gelé

    V5.0 RC1

    tag V5.0.rc1

    Moteur de workflows multi-hôte. Gelé sur la branche frozen/v5 ; plus aucun développement.

  2. NOW En cours

    V6 Core pre-alpha

    packages/bw-core

    Hooks Claude Code, scope des preuves, usage interne sur deux dépôts.

  3. NEXT Après l'usage interne

    V6 Core alpha

    première release taguée

    Publiée une fois que la période d'usage interne montre de vraies détections et peu de faux blocages. D'autres hôtes suivront sous forme de petits adaptateurs.

STATEMENTdéclaration

PRE-ALPHA

Core est utilisable aujourd'hui et tourne sur les dépôts du mainteneur. Son format de policy peut encore changer avant l'alpha.

Tout ici est gratuit et open source. Il n'y a ni offre payante, ni compte, ni télémétrie.

LICENSINGlicences

licences
PartieLicenceÉtat
V6 Core (packages/bw-core)Apache-2.0actif
Site web et reste du dépôtAGPL-3.0-onlyactif
Plugin V5AGPL-3.0-onlysur frozen/v5gelé

07DocsDOCS

Tout est dans le dépôt.

Les guides sont rédigés en anglais et en chinois traditionnel. Chaque langue de ce site a un court README sur GitHub.

08FAQFAQ

Questions fréquentes, réponses directes.

Autre chose ? Ouvrez une issue sur GitHub. GitHub Issues

Est-ce que ça ralentit Claude Code ?

Les hooks qui traitent une vérification ou un effet de bord calculent le hash de l'arbre de travail avec Git, ce qui prend quelques millisecondes dans un dépôt normal. Les très gros dépôts paient davantage à chacun de ces appels.

Va-t-il renvoyer l'agent indéfiniment ?

Il renvoie l'agent avec la raison et le déroulé de la session jusque-là : exécutions, échecs consécutifs, nombre de renvois. L'agent peut alors s'arrêter et vous dire clairement quelle vérification échoue sans cesse.

L'agent peut-il le désactiver ?

Pas directement. Core refuse les modifications de la policy et du registre par l'agent, et refuse bw init et le règlement manuel d'une action. Désinstaller le plugin, ou modifier ces fichiers par des moyens détournés, relève des propres règles d'autorisation de Claude Code : gardez donc ces demandes de confirmation activées.

Envoie-t-il quoi que ce soit ailleurs ?

Il n'y a ni serveur ni télémétrie. Ses seuls appels réseau sont des vérifications en lecture seule avec vos propres git, gh et npm, pour confirmer si un effet de bord a eu lieu. Le registre reste dans .git/better-workflows/.

Et Codex, Gemini CLI ou Qwen Code ?

Ils utilisaient V5, qui est gelé. Core est indépendant de l'hôte, et des adaptateurs pour eux sont prévus après l'alpha.

Essayez en quelques secondes

Lancer une commande n'est pas une preuve. Les fichiers, si.

Lancez la démo sans Claude, puis installez-le sur un dépôt et demandez une modification.

Installer pour Claude CodeVoir sur GitHub