Better WorkflowsV6
Italiano
V6 Corepre-alpha

Solo prove fresche.
Ignoto? Ci si ferma.

Un plugin per Claude Code che impedisce a un agente AI di concludere su un test verde ormai superato, e di ripetere o accumulare effetti collaterali di cui non ha mai visto il risultato. Ciò che può fare viene da un file di policy che scrivi tu, mai dal prompt.

  • Prove attuali
  • Al massimo una volta
  • La policy, non il prompt
  • Fail-closed
Installa per Claude Code Guardalo fermarsi GitHub

stale-green · un verde superato, poi un push ritentato

demo
  1. claude correggi il bug in sum.mjs, non serve rieseguire i test
  2. testnode --test passa sui file a1f3
  3. editl'agente modifica sum.mjs, ora i file sono 9c07
  4. stop“Fatto. I test passano.”
  5. bwRimandato indietro: test è passato l'ultima volta su a1f3; da allora i file sono cambiati.
  6. testl'agente riesegue node --test: 1 errore, lo corregge, passa su b2e8
  7. pushgit push va in timeout dopo che il push è andato a segno
  8. pushl'agente ritenta git push
  9. bwNegato: git-push è già riuscito su questo commit.

SENT BACKCore ha fermato l'agente due volte: una prima che concludesse su un vecchio esito positivo, una prima che facesse di nuovo push. Entrambe le volte è stato rimandato indietro con il motivo.

Cosa ha controllato Core

2 STOP · 0 FALSI COMPLETAMENTI
  1. Policyda .better-workflows/policy.jsonPASS
  2. Provatest sui file così come sono oraBLOCKED
  3. Riesecuzioneil test passa su b2e8PASS
  4. Azionegit-push, prima voltaPASS
  5. Al massimo una voltastesso push, stesso commitBLOCKED

Abbreviato dalla demo stale-green del repository; gli id degli alberi sono indicativi. Esegui tu stesso la demo completa in pochi secondi, senza Claude.

01PrincipiPRINCIPLES

Tre regole che diventano più utili man mano che i modelli migliorano.

Un agente più capace scrive più codice per sessione ed esegue più comandi da solo. Queste regole non dipendono dalla prudenza dell'agente; valgono qualunque cosa dica.

WITHOUT vs WITHla stessa sessione

SituazioneAgente da soloCon Core
Test passati, poi un file è cambiato“I test passano.”Rimandato indietro a rieseguirli sui file attuali.
npm test | tailContato come verde; l'exit code è quello di tail.Non conta mai; Stop spiega perché.
Un solo file di spec invece della suiteContato come “i test passano”.Con exact conta solo il comando completo.
Il push va in timeout dopo essere andato a segnoRipete il push.Lo stesso push sullo stesso commit viene rifiutato.
Il prompt dice “puoi pubblicare”Pubblica.Decide la policy: allow, ask o deny.

AUTHORITYda dove viene l'autorità

  1. L1
    policy.json

    Scritto e modificato da una persona. Core rifiuta le modifiche dirette dell'agente.

    FONTE
  2. L2
    Permessi di Claude Code

    Restano validi. allow nella policy non concede mai più di quanto concederebbe Claude Code.

  3. L3
    Hook di Core

    Applicano la policy a ogni comando, modifica e arresto.

  4. L4
    Il prompt

    Descrive l'obiettivo. Non ha alcuna autorità.

    NESSUNA

02Come funzionaHOW IT WORKS

Sei hook, un registro in .git.

Core gira dentro gli hook di Claude Code. Niente da avviare, nessun server, nessun account; lo stato si trova in .git/better-workflows/ di ogni repository.

HOOKSgli hook

  1. SessionStart: dice all'agente quali controlli devono passare e quali effetti collaterali sono in sospeso, e avvisa se la policy non è valida o se gh serve ma non è utilizzabile.
  2. PreToolUse: consente, chiede o nega ogni effetto collaterale, e rifiuta le modifiche alla policy e al registro.
  3. PostToolUse: registra ogni controllo con l'albero Git su cui è stato eseguito, e ogni effetto collaterale con il suo exit code.
  4. Stop: se dei file sono cambiati e un controllo richiesto manca, è fallito o è superato, rimanda indietro l'agente una volta con il motivo; la volta successiva si limita ad avvisare.
  5. bw status (un comando, non un hook): mostra a te lo stesso stato.
STOP

Conclusione

prove legate ai file

Un test, un lint, un typecheck o una build contano solo se sono passati, se il loro exit code ha determinato l'esito della riga, se nessun file è cambiato durante l'esecuzione e se i file sono ancora esattamente quelli su cui sono stati eseguiti.

Facoltativi

  • exact: conta solo il comando completo, e cwd stabilisce dove deve essere eseguito.
  • scope (con exact): una modifica fuori dalle directory indicate lascia il risultato valido.
  • ignore (per tutta la policy): l'output scritto da un controllo, come la coverage, non conta come modifica.
PRETOOLUSE

Effetti collaterali

al massimo una volta, l'ignoto ferma

Push, creazione e merge di PR, release, pubblicazione di pacchetti e i tuoi tipi personalizzati richiedono ciascuno allow dalla policy. Solo l'exit code 0 è un esito noto.

Controlli in sola lettura usati per risolvere un esito ignoto

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

RULESregole che valgono sempre

  • R1

    Una policy non valida nega ogni effetto collaterale invece di ripiegare sui valori predefiniti.

  • R2

    Un permesso scaduto torna ad ask. Solo una persona può prorogarlo, modificando la policy.

  • R3

    I comandi che Core non sa leggere, come eval o sh -c, sono trattati come opachi e richiedono conferma.

  • R4

    Il registro è append-only e concatenato tramite hash; bw verify rileva voci modificate o rimosse e un'ultima riga scritta a metà, ma non voci intere tagliate dalla fine.

03HostHOSTS

Prima di tutto Claude Code.

Core è indipendente dall'host; ogni host richiede un piccolo adattatore. Claude Code è il primo e oggi l'unico supportato.

Supporto per host e sistemi operativi
HostmacOSLinuxWindows
Claude CodePrimo hostSupportato, testato in CISupportato, testato in CINon testato
CodexSolo V5, congelatoPianificatoPianificatoPianificato
Gemini CLISolo V5, congelatoPianificatoPianificatoPianificato
Qwen CodeSolo V5, congelatoPianificatoPianificatoPianificato

La CI esegue Core su ogni pull request.macOS 15 e Ubuntu 24.04, Node 22.23.3 e 24.21.0.

04IniziaGET STARTED

Tre comandi, poi chiedi una modifica.

Richiede Node.js 22.14 o successivo, Git e Claude Code con supporto ai plugin.

  1. 1

    Clona Core

    Una volta per macchina. Se qui usavi V5, sposta prima ~/.better-workflows in ~/.better-workflows-V5 e fai puntare SBW_STATE_ROOT lì.

  2. 2

    Aggiungi il plugin

    Installalo per repository con --scope local, così nulla viene scritto nei file di cui fai commit.

  3. 3

    Scrivi una policy

    bw init scrive .better-workflows/policy.json. Fanne il commit così tutti hanno le stesse regole.

  4. La guida completa tratta i tuoi controlli, gli effetti collaterali e gli esiti ignoti. Guida introduttiva

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

Facoltativo: esegui entrambi gli scenari senza Claude, in pochi secondi.

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

Poi provalo

Cambia una riga in questo repository e non eseguire i test.

Quando Claude Code prova a concludere, viene rimandato indietro e gli viene detto quale controllo manca.

05LimitiLIMITS

Cosa ferma e cosa non può vedere.

Un controllo è utile solo se ne conosci i confini.

Ferma

Errori osservabili

  • Concludere su un'esecuzione dei test superata o fallita, o su una parziale quando il controllo è marcato exact
  • Una pipe o || true che nasconde un errore
  • Un push, merge, release o pubblicazione ripetuti
  • Effetti collaterali mentre uno precedente ha esito ignoto
  • L'agente che modifica direttamente la propria policy o il registro

Non fa

Fuori dalla sua vista

  • Vedere effetti collaterali dentro uno script, a meno che la policy non nomini quello script
  • Giudicare se i tuoi test sono abbastanza buoni
  • Costruire un grafo delle dipendenze: uno scope deve nominare tutto ciò da cui un controllo dipende
  • Contare i file ignorati da Git come parte della prova

Lascia a te

Decisioni di una persona

  • Risolvere un effetto collaterale il cui esito non si può rileggere
  • Prorogare un permesso oltre il suo expiresAt
  • Scegliere cosa copre uno scope
  • Decidere quando una sessione sta girando in tondo
Core blocca gli errori sopra elencati. Non è stato misurato se riduca le rilavorazioni o le decisioni sbagliate nei task lunghi; è a questo che serve l'attuale periodo di uso interno.
  1. B1Il parser della shell non cresce: per un comando che non sa leggere viene chiesta conferma prima che venga eseguito, e un test nascosto dentro eval o sh -c non conta mai come prova.
  2. B2Core si limita a contare come sta andando una sessione. Se stia convergendo lo giudicate l'agente o tu.
  3. B3Pull request e release vengono riconciliate con gh; senza di esso restano ignote finché non le risolvi tu.

06StatoSTATUS

A che punto è il progetto.

V6 sostituisce il motore di workflow di V5 con un piccolo core. Le date si danno quando vengono raggiunte.

  1. DONE Congelato

    V5.0 RC1

    tag V5.0.rc1

    Motore di workflow multi-host. Congelato sul branch frozen/v5; nessun nuovo sviluppo.

  2. NOW In corso

    V6 Core pre-alpha

    packages/bw-core

    Hook di Claude Code, scope delle prove, uso interno su due repository.

  3. NEXT Dopo l'uso interno

    V6 Core alpha

    prima release con tag

    Pubblicata quando il periodo di uso interno mostrerà errori realmente intercettati e pochi blocchi falsi. Altri host seguiranno come piccoli adattatori.

STATEMENTdichiarazione

PRE-ALPHA

Core è utilizzabile oggi e gira sui repository del maintainer. Il formato della policy può ancora cambiare prima dell'alpha.

Tutto qui è gratuito e open source. Non ci sono piani a pagamento, account o telemetria.

LICENSINGlicenze

licenze
ParteLicenzaStato
V6 Core (packages/bw-core)Apache-2.0attiva
Sito web e resto del repositoryAGPL-3.0-onlyattiva
Plugin V5AGPL-3.0-onlysu frozen/v5congelata

07DocumentazioneDOCS

Tutto è nel repository.

Le guide sono scritte in inglese e in cinese tradizionale. Ogni lingua di questo sito ha un breve README su GitHub.

08FAQFAQ

Domande frequenti, risposte dirette.

Altro? Apri una issue su GitHub. GitHub Issues

Rallenta Claude Code?

Gli hook che gestiscono un controllo o un effetto collaterale calcolano l'hash del working tree con Git, il che richiede millisecondi in un repository normale. I repository molto grandi pagano di più a ogni chiamata di questo tipo.

Rischia di rimandare indietro l'agente all'infinito?

Rimanda indietro l'agente con il motivo e l'andamento della sessione finora: esecuzioni, errori consecutivi, volte in cui è già stato rimandato. L'agente può allora fermarsi e dirti chiaramente quale controllo continua a fallire.

L'agente può disattivarlo?

Non direttamente. Core rifiuta le modifiche dell'agente alla policy e al registro, e rifiuta bw init e la risoluzione manuale di un'azione. Disinstallare il plugin, o modificare quei file per vie traverse, è regolato dalle regole di permesso di Claude Code stesso, quindi tieni attive quelle richieste di conferma.

Invia dati da qualche parte?

Non c'è alcun server né telemetria. Le sue uniche chiamate di rete sono verifiche in sola lettura con i tuoi git, gh e npm, per confermare se un effetto collaterale è avvenuto. Il registro resta in .git/better-workflows/.

E Codex, Gemini CLI o Qwen Code?

Usavano V5, che è congelato. Core è indipendente dall'host, e gli adattatori per loro sono pianificati dopo l'alpha.

Provalo in pochi secondi

Eseguire un comando non è una prova. I file sì.

Esegui la demo senza Claude, poi installalo su un repository e chiedi una modifica.

Installa per Claude CodeVedi su GitHub