Better WorkflowsV6
Português (Brasil)
V6 Corepre-alpha

Só vale prova atual.
Desconhecido? Pare.

Um plugin para o Claude Code que impede um agente de IA de concluir com base em um teste verde desatualizado, e de repetir ou acumular efeitos colaterais cujo resultado nunca viu. O que ele pode fazer vem de um arquivo de policy escrito por você, nunca do prompt.

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

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

demo
  1. claude corrija o bug em sum.mjs, não precisa rodar os testes de novo
  2. testnode --test passa nos arquivos a1f3
  3. edito agente edita sum.mjs, os arquivos agora são 9c07
  4. stop“Pronto. Os testes passam.”
  5. bwMandado de volta: test passou pela última vez em a1f3; os arquivos mudaram desde então.
  6. testo agente roda node --test de novo: 1 falha, corrige, passa em b2e8
  7. pushgit push dá timeout depois que o push já chegou
  8. pusho agente tenta git push de novo
  9. bwNegado: git-push já teve sucesso neste commit.

SENT BACKO Core parou o agente duas vezes: uma quando ia concluir com uma aprovação antiga, outra quando ia fazer push de novo. Nas duas vezes ele foi mandado de volta com o motivo.

O que o Core verificou

2 PARADAS · 0 FALSOS CONCLUÍDOS
  1. Policyde .better-workflows/policy.jsonPASS
  2. Evidênciateste nos arquivos 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

Resumido da demo stale-green do repositório; os ids de tree são ilustrativos. Rode a demo completa você mesmo em poucos segundos, sem o Claude.

01PrincípiosPRINCIPLES

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

Um agente mais forte escreve mais código por sessão e roda mais comandos por conta própria. Essas regras não dependem de o agente ser cuidadoso; valem não importa o que ele diga.

WITHOUT vs WITHa mesma sessão

SituaçãoSó o agenteCom o Core
Os testes passaram, depois um arquivo mudou“Os testes passam.”Mandado de volta para rodar nos arquivos atuais.
npm test | tailContado como verde; o código de saída é do tail.Nunca conta; o Stop explica por quê.
Um arquivo spec no lugar da suíteContado como “os testes passam”.Com exact, só o comando completo conta.
O push dá timeout depois de chegarFaz push de novo.O mesmo push no mesmo commit é recusado.
O prompt diz “você pode 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 edições diretas do agente nele.

    ORIGEM
  2. L2
    Permissões do Claude Code

    Continuam valendo. 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 parada.

  4. L4
    O prompt

    Descreve o objetivo. Não carrega nenhuma autoridade.

    NENHUMA

02Como funcionaHOW IT WORKS

Seis hooks, um registro no .git.

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

HOOKSos hooks

  1. SessionStart: diz ao agente quais verificações precisam passar e quais efeitos colaterais ainda não foram resolvidos, 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 colateral, e recusa edições na policy e no registro.
  3. PostToolUse: registra cada verificação com a tree do Git em que rodou, e cada efeito colateral com seu código de saída.
  4. Stop: se arquivos mudaram e uma verificação obrigatória estiver faltando, tiver falhado ou estiver desatualizada, manda o agente de volta uma vez com o motivo; na vez seguinte só avisa.
  5. bw status (um comando, não um hook): mostra o mesmo estado para você.
STOP

Conclusão

evidência presa aos arquivos

Um teste, lint, typecheck ou build só conta se passou, se o próprio código de saída decidiu a linha, se nenhum arquivo mudou enquanto rodava, e se os arquivos ainda são exatamente aqueles em que rodou.

Opcional

  • exact: só o comando completo conta, e cwd define onde ele precisa rodar.
  • scope (com exact): uma mudança fora dos diretórios indicados mantém o resultado atual.
  • ignore (policy inteira): a saída que uma verificação grava, como cobertura, não conta como mudança.
PRETOOLUSE

Efeitos colaterais

no máximo uma vez, o desconhecido para

Pushes, criação e merge de PRs, releases, publicação de pacotes e 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 somente leitura usadas para resolver um resultado desconhecido

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

RULESregras que valem sempre

  • R1

    Uma policy inválida nega todo efeito colateral em vez de cair nos padrões.

  • R2

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

  • R3

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

  • R4

    O registro é append-only e encadeado por hash; bw verify detecta entradas editadas ou removidas e uma última linha escrita pela metade, mas não entradas inteiras cortadas do final.

03HostsHOSTS

Claude Code primeiro.

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

Suporte a hosts e sistemas operacionais
HostmacOSLinuxWindows
Claude CodePrimeiro hostSuportado, testado em CISuportado, testado em CINão testado
CodexSó V5, congeladoPlanejadoPlanejadoPlanejado
Gemini CLISó V5, congeladoPlanejadoPlanejadoPlanejado
Qwen CodeSó V5, congeladoPlanejadoPlanejadoPlanejado

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

04Primeiros passosGET STARTED

Três comandos, depois peça uma mudança.

Requer Node.js 22.14 ou mais recente, Git e Claude Code com suporte a plugins.

  1. 1

    Clone o Core

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

  2. 2

    Adicione o plugin

    Instale por repositório com --scope local, para que nada seja gravado em arquivos que você commita.

  3. 3

    Escreva uma policy

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

  4. O passo a passo completo cobre suas próprias verificações, efeitos colaterais e resultados desconhecidos. Primeiros passos

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: rode os dois cenários sem o Claude, em poucos segundos.

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

Depois experimente

Mude uma linha neste repositório e não rode os testes.

Quando o Claude Code tenta concluir, ele é mandado de volta e fica sabendo qual verificação está faltando.

05LimitesLIMITS

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

Uma barreira só é útil se você conhece os limites dela.

Impede

Erros observáveis

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

Não faz

Fora do seu alcance

  • Ver efeitos colaterais dentro de um script, a não ser que a policy nomeie esse script
  • Julgar se seus testes são bons o bastante
  • Montar um grafo de dependências: um scope precisa nomear tudo de que uma verificação depende
  • Contar arquivos ignorados pelo Git como parte da evidência

Deixa com você

Decisões de uma pessoa

  • Resolver um efeito colateral cujo resultado não pode ser lido de volta
  • Estender uma permissão além do expiresAt
  • Escolher o que um scope cobre
  • Decidir quando uma sessão está andando em círculos
O Core bloqueia os erros acima. Ainda não foi medido se ele reduz retrabalho ou decisões erradas em tarefas longas; é para isso que serve o período atual de uso próprio.
  1. B1O parser de shell não cresce: um comando que ele não consegue ler gera um pedido de confirmação antes de rodar, 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á indo. Se ela está convergindo, cabe ao agente ou a você julgar.
  3. B3Pull requests e releases são reconciliados com o gh; sem ele, ficam desconhecidos até você resolvê-los.

06StatusSTATUS

Onde o projeto está.

O V6 substitui o motor de workflows do V5 por um núcleo pequeno. As datas vêm 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 trabalho novo.

  2. NOW Em andamento

    V6 Core pre-alpha

    packages/bw-core

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

  3. NEXT Depois do uso próprio

    V6 Core alpha

    primeira release com tag

    Publicado quando o período de uso próprio mostrar erros reais pegos e poucos bloqueios falsos. Mais hosts vêm depois, como pequenos adaptadores.

STATEMENTdeclaração

PRE-ALPHA

O Core já pode ser usado hoje e roda 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 ou telemetria.

LICENSINGlicenciamento

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

07DocumentaçãoDOCS

Está tudo no repositório.

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

08PerguntasFAQ

Perguntas comuns, respostas diretas.

Outra dúvida? Abra uma issue no GitHub. GitHub Issues

Ele deixa o Claude Code mais lento?

Os hooks que tratam uma verificação ou um efeito colateral calculam o hash da árvore de trabalho com o Git, o que leva milissegundos em um repositório normal. Repositórios muito grandes pagam mais a cada chamada desse tipo.

Ele pode travar mandando o agente de volta para sempre?

Ele manda o agente de volta com o motivo e com o andamento da sessão até ali: execuções, falhas seguidas, vezes que já foi mandado de volta. O agente pode então parar e dizer claramente qual verificação continua falhando.

O agente consegue desligá-lo?

Não diretamente. O Core recusa as edições do agente na policy e no registro, e recusa bw init e a resolução manual de uma ação. Desinstalar o plugin, ou alterar esses arquivos por caminhos indiretos, fica a cargo das regras de permissão do próprio Claude Code, então mantenha essas confirmações ativadas.

Ele envia algo para algum lugar?

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

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

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

Experimente em poucos segundos

Rodar um comando não é prova. Os arquivos são.

Rode a demo sem o Claude, depois instale em um repositório e peça uma mudança.

Instalar no Claude CodeVer no GitHub