Better WorkflowsV6
Português
V6 Corepre-alpha

Só conta prova atual.
Desconhecido? Parar.

Um plugin para o Claude Code que impede um agente de IA de concluir com base num teste verde desatualizado, e de repetir ou acumular efeitos secundários cujo resultado nunca viu. O que pode fazer vem de um ficheiro de policy escrito por si, nunca do prompt.

  • Evidências atuais
  • No máximo uma vez
  • Policy, não prompt
  • Fail-closed
Instalar no Claude Code Veja-o a parar GitHub

stale-green · um verde desatualizado, depois um push repetido

demo
  1. claude corrige o bug em sum.mjs, não é preciso voltar a correr os testes
  2. testnode --test passa nos ficheiros a1f3
  3. edito agente edita sum.mjs, os ficheiros passam a ser 9c07
  4. stop«Feito. Os testes passam.»
  5. bwMandado para trás: test passou pela última vez em a1f3; os ficheiros mudaram desde então.
  6. testo agente volta a correr node --test: 1 falha, corrige-a, passa em b2e8
  7. pushgit push esgota o tempo depois de o push já ter chegado
  8. pusho agente repete git push
  9. bwNegado: git-push já foi bem-sucedido neste commit.

SENT BACKO Core travou o agente duas vezes: uma quando ia concluir com base num resultado aprovado antigo, outra quando ia fazer push outra vez. Das duas vezes foi mandado para trás com o motivo.

O que o Core verificou

2 PARAGENS · 0 FALSOS CONCLUÍDOS
  1. Policyde .better-workflows/policy.jsonPASS
  2. Evidênciateste nos ficheiros tal como estão agoraBLOCKED
  3. Nova execuçãoteste passa em b2e8PASS
  4. Açãogit-push, primeira vezPASS
  5. No máximo uma vezmesmo push, mesmo commitBLOCKED

Abreviado a partir da demo stale-green do repositório; os ids de tree são ilustrativos. Corra a demo completa em poucos segundos, sem o Claude.

01PrincípiosPRINCIPLES

Três regras que ficam mais úteis à medida que os modelos ficam mais fortes.

Um agente mais forte escreve mais código por sessão e executa mais comandos por conta própria. Estas regras não dependem do cuidado do agente; mantêm-se, diga ele o que disser.

WITHOUT vs WITHa mesma sessão

SituaçãoSó o agenteCom o Core
Os testes passaram, depois um ficheiro mudou«Os testes passam.»Mandado para trás para voltar a correr nos ficheiros atuais.
npm test | tailContado como verde; o código de saída é do tail.Nunca conta; o Stop diz porquê.
Um ficheiro spec em vez da suiteContado como «os testes passam».Com exact, só conta o comando completo.
O push esgota o tempo depois de chegarFaz push outra vez.O mesmo push no mesmo commit é recusado.
O prompt diz «podes publicar»Publica.A policy decide: allow, ask ou deny.

AUTHORITYde onde vem a autoridade

  1. L1
    policy.json

    Escrito e alterado por uma pessoa. O Core recusa que o agente o edite diretamente.

    ORIGEM
  2. L2
    Permissões do Claude Code

    Continuam a aplicar-se. allow na policy nunca concede mais do que o Claude Code concederia.

  3. L3
    Hooks do Core

    Aplicam a policy em cada comando, edição e paragem.

  4. L4
    O prompt

    Descreve o objetivo. Não tem qualquer autoridade.

    NENHUMA

02Como funcionaHOW IT WORKS

Seis hooks, um registo em .git.

O Core corre dentro dos próprios hooks do Claude Code. Nada para arrancar, sem servidor, sem conta; o estado fica em .git/better-workflows/ de cada repositório.

HOOKSos hooks

  1. SessionStart: diz ao agente que verificações têm de passar e que efeitos secundários estão por resolver, e avisa se a policy for inválida ou se o gh for necessário mas não puder ser usado.
  2. PreToolUse: permite, pergunta ou nega cada efeito secundário, e recusa edições à policy e ao registo.
  3. PostToolUse: regista cada verificação com a tree do Git em que correu, e cada efeito secundário com o seu código de saída.
  4. Stop: se houve ficheiros alterados e uma verificação obrigatória estiver em falta, tiver falhado ou estiver desatualizada, manda o agente para trás uma vez com o motivo; da vez seguinte apenas avisa.
  5. bw status (um comando, não um hook): mostra-lhe o mesmo estado.
STOP

Concluir

evidência ligada aos ficheiros

Um teste, lint, typecheck ou build só conta se passou, se foi o seu próprio código de saída a decidir a linha, se nenhum ficheiro mudou enquanto corria, e se os ficheiros ainda são exatamente aqueles em que correu.

Opcional

  • exact: só conta o comando completo, e cwd define onde tem de correr.
  • scope (com exact): uma alteração fora dos diretórios indicados mantém o resultado atual.
  • ignore (toda a policy): o output que uma verificação escreve, como a cobertura, não conta como alteração.
PRETOOLUSE

Efeitos secundários

no máximo uma vez, o desconhecido para

Pushes, criação e merge de PRs, releases, publicação de pacotes e os seus próprios tipos personalizados precisam, cada um, de allow na policy. Só o código de saída 0 é um resultado conhecido.

Verificações só de leitura usadas para resolver um resultado desconhecido

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

RULESregras que se mantêm

  • R1

    Uma policy inválida nega todos os efeitos secundários em vez de recorrer a valores predefinidos.

  • R2

    Uma permissão expirada volta a ask. Só uma pessoa a prolonga, editando a policy.

  • R3

    Comandos que o Core não consegue ler, como eval ou sh -c, são tratados como opacos e é pedida confirmação.

  • R4

    O registo é append-only e encadeado por hash; bw verify deteta entradas editadas ou removidas e uma última linha escrita a meio, mas não entradas inteiras cortadas do fim.

03HostsHOSTS

Primeiro o Claude Code.

O Core é neutro em relação ao host; cada host precisa de um pequeno adaptador. O Claude Code é o primeiro e o único suportado hoje.

Suporte de hosts e sistemas operativos
HostmacOSLinuxWindows
Claude CodePrimeiro hostSuportado, testado em CISuportado, testado em CINão testado
CodexSó V5, congeladoPlaneadoPlaneadoPlaneado
Gemini CLISó V5, congeladoPlaneadoPlaneadoPlaneado
Qwen CodeSó V5, congeladoPlaneadoPlaneadoPlaneado

A CI corre o Core em cada pull request.macOS 15 e Ubuntu 24.04, Node 22.23.3 e 24.21.0.

04ComeçarGET STARTED

Três comandos, depois peça uma alteração.

Requer Node.js 22.14 ou posterior, Git e Claude Code com suporte para plugins.

  1. 1

    Clonar o Core

    Uma vez por máquina. Se já usou o V5 aqui, mova primeiro ~/.better-workflows para ~/.better-workflows-V5 e aponte SBW_STATE_ROOT para lá.

  2. 2

    Adicionar o plugin

    Instale-o por repositório com --scope local, para que nada seja escrito em ficheiros que faz commit.

  3. 3

    Escrever uma policy

    bw init escreve .better-workflows/policy.json. Faça commit para que todos tenham as mesmas regras.

  4. O guia completo cobre as suas próprias verificações, efeitos secundários e resultados desconhecidos. Guia de introdução

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

Opcional: corra os dois cenários sem o Claude, em poucos segundos.

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

Depois experimente

Altera uma linha neste repositório e não corras os testes.

Quando o Claude Code tenta concluir, é mandado para trás e fica a saber que verificação falta.

05LimitesLIMITS

O que impede e o que não consegue ver.

Uma barreira só é útil se conhecer os seus limites.

Impede

Erros observáveis

  • Concluir com uma execução de testes desatualizada ou falhada, ou com uma parcial quando a verificação está marcada como exact
  • Um pipe ou || true a esconder uma falha
  • Um push, merge, release ou publish repetido
  • Efeitos secundários enquanto um anterior é desconhecido
  • O agente editar diretamente a sua própria policy ou o seu registo

Não faz

Fora do seu alcance

  • Ver efeitos secundários dentro de um script, a menos que a policy indique esse script
  • Avaliar se os seus testes são bons o suficiente
  • Construir um grafo de dependências: um scope tem de indicar tudo aquilo de que uma verificação depende
  • Contar ficheiros ignorados pelo Git como parte da evidência

Deixa consigo

Decisões de uma pessoa

  • Resolver um efeito secundário cujo resultado não pode ser lido de volta
  • Prolongar uma permissão para além do seu expiresAt
  • Escolher o que um scope cobre
  • Decidir quando uma sessão está a andar em círculos
O Core bloqueia os erros acima. Ainda não foi medido se reduz retrabalho ou decisões erradas em tarefas longas; é para isso que serve o atual período de uso próprio.
  1. B1O parser de shell não cresce: um comando que não consegue ler leva a um pedido de confirmação antes de correr, e um teste escondido dentro de eval ou sh -c nunca conta como evidência.
  2. B2O Core só contabiliza como a sessão está a correr. Se está a convergir, cabe ao agente ou a si julgar.
  3. B3Pull requests e releases são reconciliados com o gh; sem ele, ficam desconhecidos até os resolver.

06EstadoSTATUS

Onde está o projeto.

O V6 substitui o motor de workflows do V5 por um núcleo pequeno. As datas chegam quando as metas são cumpridas.

  1. DONE Congelado

    V5.0 RC1

    tag V5.0.rc1

    Motor de workflows multi-host. Congelado no branch frozen/v5; sem novo desenvolvimento.

  2. NOW Em curso

    V6 Core pre-alpha

    packages/bw-core

    Hooks do Claude Code, scope de evidência, uso próprio em dois repositórios.

  3. NEXT Após o uso próprio

    V6 Core alpha

    primeira release com tag

    Publicado quando o período de uso próprio mostrar erros reais apanhados e poucos bloqueios falsos. Mais hosts seguem-se como pequenos adaptadores.

STATEMENTdeclaração

PRE-ALPHA

O Core já pode ser usado hoje e corre nos repositórios do próprio mantenedor. O formato da policy ainda pode mudar antes da alpha.

Tudo aqui é gratuito e open source. Não há plano pago, conta nem telemetria.

LICENSINGlicenciamento

licenciamento
ParteLicençaEstado
V6 Core (packages/bw-core)Apache-2.0ativo
Site e restante repositórioAGPL-3.0-onlyativo
Plugin V5AGPL-3.0-onlyem frozen/v5congelado

07DocumentaçãoDOCS

Está tudo no repositório.

Os guias estão escritos em inglês e chinês tradicional. Cada idioma deste site tem um README curto no GitHub.

08PerguntasFAQ

Perguntas frequentes, respostas diretas.

Outra coisa? Abra um issue no GitHub. GitHub Issues

Torna o Claude Code mais lento?

Os hooks que tratam uma verificação ou um efeito secundário calculam o hash da árvore de trabalho com o Git, o que demora milissegundos num repositório normal. Repositórios muito grandes pagam mais em cada uma dessas chamadas.

Pode ficar preso a mandar o agente para trás para sempre?

Manda o agente para trás com o motivo e com o andamento da sessão até ali: execuções, falhas seguidas, vezes que já foi mandado para trás. O agente pode então parar e dizer-lhe claramente que verificação continua a falhar.

O agente pode desativá-lo?

Não diretamente. O Core recusa as edições do agente à policy e ao registo, e recusa bw init e a resolução manual de uma ação. Desinstalar o plugin, ou alterar esses ficheiros por vias indiretas, fica sujeito às regras de permissões do próprio Claude Code, por isso mantenha esses pedidos de confirmação ativos.

Envia alguma coisa para algum lado?

Não há servidor nem telemetria. As únicas chamadas de rede são verificações só de leitura com o seu próprio git, gh e npm, para confirmar se um efeito secundário aconteceu. O registo fica em .git/better-workflows/.

E o Codex, o Gemini CLI ou o Qwen Code?

Corriam o V5, que está congelado. O Core é neutro em relação ao host, e estão planeados adaptadores para eles depois da alpha.

Experimente em poucos segundos

Correr um comando não é prova. Os ficheiros são.

Corra a demo sem o Claude, depois instale-o num repositório e peça uma alteração.

Instalar no Claude CodeVer no GitHub