Better WorkflowsV6
Polski
V6 Corepre-alpha

Dowód musi być świeży.
Nieznane znaczy stop.

Plugin do Claude Code, który nie pozwala agentowi AI zakończyć pracy na nieaktualnym zielonym teście ani powtarzać czy nawarstwiać skutków ubocznych, których wyniku nigdy nie zobaczył. To, co może zrobić, wynika z pliku policy, który piszesz Ty, nigdy z promptu.

  • Aktualne dowody
  • Najwyżej raz
  • Policy, nie prompt
  • Fail-closed
Zainstaluj w Claude Code Zobacz, jak zatrzymuje GitHub

stale-green · nieaktualna zieleń, potem ponowiony push

demo
  1. claude napraw błąd w sum.mjs, nie trzeba ponownie uruchamiać testów
  2. testnode --test przechodzi na plikach a1f3
  3. editagent edytuje sum.mjs, pliki to teraz 9c07
  4. stop„Gotowe. Testy przechodzą.”
  5. bwOdesłany: test ostatnio przeszedł na a1f3; od tego czasu pliki się zmieniły.
  6. testagent ponownie uruchamia node --test: 1 błąd, naprawia go, przechodzi na b2e8
  7. pushgit push przekracza limit czasu, gdy push już dotarł
  8. pushagent ponawia git push
  9. bwOdmowa: git-push już się powiódł dla tego commita.

SENT BACKCore dwa razy zatrzymał agenta: raz przed zakończeniem na starym udanym wyniku, raz przed ponownym push. Za każdym razem agent został odesłany z podaniem powodu.

Co sprawdził Core

2 ZATRZYMANIA · 0 FAŁSZYWYCH UKOŃCZEŃ
  1. Policyz .better-workflows/policy.jsonPASS
  2. Dowodytest na plikach w obecnym stanieBLOCKED
  3. Ponowienietest przechodzi na b2e8PASS
  4. Akcjagit-push, pierwszy razPASS
  5. Najwyżej razten sam push, ten sam commitBLOCKED

Skrócone z demo stale-green z repozytorium; identyfikatory tree są poglądowe. Uruchom pełne demo samodzielnie w kilka sekund, bez Claude.

01ZasadyPRINCIPLES

Trzy zasady, które zyskują na znaczeniu, gdy modele stają się silniejsze.

Silniejszy agent pisze więcej kodu w jednej sesji i sam uruchamia więcej poleceń. Te zasady nie zależą od ostrożności agenta; obowiązują bez względu na to, co mówi.

WITHOUT vs WITHta sama sesja

SytuacjaSam agentZ Core
Testy przeszły, potem zmienił się plik„Testy przechodzą.”Odesłany, by uruchomić je ponownie na bieżących plikach.
npm test | tailLiczone jako zielone; kod wyjścia należy do tail.Nigdy się nie liczy; Stop podaje powód.
Jeden plik spec zamiast całego zestawuLiczone jako „testy przechodzą”.Z exact liczy się tylko pełne polecenie.
Push przekracza limit czasu po dotarciuRobi push ponownie.Ten sam push przy tym samym commicie zostaje odrzucony.
Prompt mówi „możesz publikować”Publikuje.Decyduje policy: allow, ask lub deny.

AUTHORITYskąd pochodzą uprawnienia

  1. L1
    policy.json

    Pisany i zmieniany przez człowieka. Core odrzuca jego bezpośrednie edycje przez agenta.

    ŹRÓDŁO
  2. L2
    Uprawnienia Claude Code

    Nadal obowiązują. allow w policy nigdy nie daje więcej, niż dałby Claude Code.

  3. L3
    Hooki Core

    Egzekwują policy przy każdym poleceniu, edycji i zakończeniu.

  4. L4
    Prompt

    Opisuje cel. Nie niesie żadnych uprawnień.

    BRAK

02Jak to działaHOW IT WORKS

Sześć hooków, jeden rejestr w .git.

Core działa w hookach samego Claude Code. Nic do uruchamiania, bez serwera, bez konta; stan jest przechowywany w .git/better-workflows/ każdego repozytorium.

HOOKShooki

  1. SessionStart: mówi agentowi, które sprawdzenia muszą przejść i które skutki uboczne są nierozstrzygnięte, oraz ostrzega, jeśli policy jest nieprawidłowa albo gh jest potrzebny, ale nie da się go użyć.
  2. PreToolUse: zezwala, pyta lub odmawia przy każdym skutku ubocznym i blokuje edycje policy oraz rejestru.
  3. PostToolUse: zapisuje każde sprawdzenie wraz z drzewem Git, na którym działało, i każdy skutek uboczny wraz z jego kodem wyjścia.
  4. Stop: jeśli pliki się zmieniły, a wymagane sprawdzenie jest brakujące, nieudane lub nieaktualne, raz odsyła agenta z podaniem powodu; następnym razem tylko ostrzega.
  5. bw status (polecenie, nie hook): pokazuje Ci ten sam stan.
STOP

Zakończenie

dowody związane z plikami

Test, lint, typecheck lub build liczy się tylko wtedy, gdy przeszedł, o wyniku zdecydował jego własny kod wyjścia, żaden plik nie zmienił się w trakcie, a pliki są nadal dokładnie tymi, na których działał.

Opcjonalnie

  • exact: liczy się tylko pełne polecenie, a cwd określa, gdzie musi zostać uruchomione.
  • scope (z exact): zmiana poza wskazanymi katalogami nie unieważnia wyniku.
  • ignore (cała policy): wyjście zapisywane przez sprawdzenie, np. coverage, nie jest liczone jako zmiana.
PRETOOLUSE

Skutki uboczne

najwyżej raz, nieznane zatrzymuje

Pushe, tworzenie i scalanie PR-ów, release'y, publikacja pakietów oraz Twoje własne typy wymagają każdorazowo allow w policy. Tylko kod wyjścia 0 jest znanym wynikiem.

Sprawdzenia tylko do odczytu używane do rozstrzygnięcia nieznanego wyniku

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

RULESzasady, które obowiązują

  • R1

    Nieprawidłowa policy odmawia każdego skutku ubocznego zamiast wracać do ustawień domyślnych.

  • R2

    Wygasłe uprawnienie wraca do ask. Przedłużyć je może tylko człowiek, edytując policy.

  • R3

    Polecenia, których Core nie potrafi odczytać, np. eval lub sh -c, są traktowane jako nieprzejrzyste i wymagają pytania.

  • R4

    Rejestr jest append-only i łańcuchowany hashami; bw verify wykrywa zmienione lub usunięte wpisy i do połowy zapisaną ostatnią linię, ale nie całe wpisy odcięte od końca.

03HostyHOSTS

Najpierw Claude Code.

Core jest niezależny od hosta; każdy host potrzebuje małego adaptera. Claude Code jest pierwszym i obecnie jedynym obsługiwanym.

Obsługa hostów i systemów operacyjnych
HostmacOSLinuxWindows
Claude CodePierwszy hostObsługiwany, testowany w CIObsługiwany, testowany w CINietestowany
CodexTylko V5, zamrożonyPlanowanyPlanowanyPlanowany
Gemini CLITylko V5, zamrożonyPlanowanyPlanowanyPlanowany
Qwen CodeTylko V5, zamrożonyPlanowanyPlanowanyPlanowany

CI uruchamia Core przy każdym pull requeście.macOS 15 i Ubuntu 24.04, Node 22.23.3 i 24.21.0.

04Pierwsze krokiGET STARTED

Trzy polecenia, potem poproś o zmianę.

Wymaga Node.js 22.14 lub nowszego, Git oraz Claude Code z obsługą pluginów.

  1. 1

    Sklonuj Core

    Raz na maszynę. Jeśli używałeś tu V5, najpierw przenieś ~/.better-workflows do ~/.better-workflows-V5 i wskaż ten katalog w SBW_STATE_ROOT.

  2. 2

    Dodaj plugin

    Instaluj go per repozytorium z --scope local, aby nic nie trafiło do plików, które commitujesz.

  3. 3

    Napisz policy

    bw init zapisuje .better-workflows/policy.json. Zacommituj go, aby wszyscy mieli te same zasady.

  4. Pełny przewodnik omawia własne sprawdzenia, skutki uboczne i nieznane wyniki. Pierwsze kroki

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

Opcjonalnie: uruchom oba scenariusze bez Claude, w kilka sekund.

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

Potem wypróbuj

Zmień jedną linię w tym repozytorium i nie uruchamiaj testów.

Gdy Claude Code spróbuje zakończyć, zostanie odesłany z informacją, którego sprawdzenia brakuje.

05OgraniczeniaLIMITS

Co zatrzymuje, a czego nie widzi.

Bramka jest użyteczna tylko wtedy, gdy znasz jej granice.

Zatrzymuje

Widoczne błędy

  • Zakończenie na nieaktualnym lub nieudanym uruchomieniu testów, albo na częściowym, gdy sprawdzenie jest oznaczone jako exact
  • Pipe lub || true ukrywające błąd
  • Powtórzony push, merge, release lub publish
  • Skutki uboczne, gdy wcześniejszy ma nieznany wynik
  • Bezpośrednią edycję własnej policy lub rejestru przez agenta

Nie

Poza jego zasięgiem

  • Widzi skutków ubocznych wewnątrz skryptu, chyba że policy wskazuje ten skrypt
  • Ocenia, czy Twoje testy są wystarczająco dobre
  • Buduje grafu zależności: scope musi wskazywać wszystko, od czego zależy sprawdzenie
  • Wlicza plików ignorowanych przez Git do dowodów

Zostawia Tobie

Decyzje człowieka

  • Rozstrzygnięcie skutku ubocznego, którego wyniku nie da się odczytać
  • Przedłużenie uprawnienia poza jego expiresAt
  • Wybór tego, co obejmuje scope
  • Ocenę, kiedy sesja kręci się w kółko
Core blokuje powyższe błędy. Nie zmierzono, czy zmniejsza ilość poprawek lub błędnych decyzji w długich zadaniach; temu służy obecny okres używania na własnych projektach.
  1. B1Parser powłoki nie jest rozbudowywany: o polecenie, którego nie potrafi odczytać, pyta się przed jego uruchomieniem, a test ukryty w eval lub sh -c nigdy nie liczy się jako dowód.
  2. B2Core tylko liczy, jak przebiega sesja. Czy zmierza do celu, ocenia agent albo Ty.
  3. B3Pull requesty i release'y są uzgadniane przez gh; bez niego pozostają nieznane, dopóki ich nie rozstrzygniesz.

06StanSTATUS

Na jakim etapie jest projekt.

V6 zastępuje silnik workflow z V5 małym rdzeniem. Daty pojawią się, gdy warunki zostaną spełnione.

  1. DONE Zamrożone

    V5.0 RC1

    tag V5.0.rc1

    Silnik workflow dla wielu hostów. Zamrożony na gałęzi frozen/v5; bez nowych prac.

  2. NOW W toku

    V6 Core pre-alpha

    packages/bw-core

    Hooki Claude Code, scope dowodów, używanie na dwóch własnych repozytoriach.

  3. NEXT Po okresie własnego użycia

    V6 Core alpha

    pierwszy otagowany release

    Opublikowany, gdy okres własnego użycia pokaże realne wyłapane błędy i niewiele fałszywych blokad. Kolejne hosty dojdą jako małe adaptery.

STATEMENToświadczenie

PRE-ALPHA

Core można używać już dziś; działa w repozytoriach opiekuna projektu. Format policy może się jeszcze zmienić przed alphą.

Wszystko tutaj jest darmowe i open source. Nie ma płatnego planu, konta ani telemetrii.

LICENSINGlicencje

licencje
CzęśćLicencjaStan
V6 Core (packages/bw-core)Apache-2.0aktywna
Strona i reszta repozytoriumAGPL-3.0-onlyaktywna
Plugin V5AGPL-3.0-onlyna frozen/v5zamrożona

07DokumentacjaDOCS

Wszystko jest w repozytorium.

Przewodniki są napisane po angielsku i w chińskim tradycyjnym. Każdy język tej strony ma krótkie README na GitHubie.

08FAQFAQ

Częste pytania, konkretne odpowiedzi.

Coś innego? Otwórz issue na GitHubie. GitHub Issues

Czy spowalnia Claude Code?

Hooki, które obsługują sprawdzenie lub skutek uboczny, liczą hash drzewa roboczego za pomocą Git, co w zwykłym repozytorium zajmuje milisekundy. Bardzo duże repozytoria płacą więcej przy każdym takim wywołaniu.

Czy może utknąć, odsyłając agenta w nieskończoność?

Odsyła agenta z powodem i przebiegiem sesji do tej pory: uruchomienia, błędy z rzędu, liczba wcześniejszych odesłań. Agent może wtedy przerwać i jasno powiedzieć Ci, które sprawdzenie ciągle nie przechodzi.

Czy agent może go wyłączyć?

Nie bezpośrednio. Core odrzuca edycje policy i rejestru przez agenta, a także bw init i ręczne rozstrzyganie akcji. Odinstalowanie pluginu lub zmiana tych plików okrężną drogą podlega własnym regułom uprawnień Claude Code, więc nie wyłączaj tych pytań.

Czy coś gdzieś wysyła?

Nie ma serwera ani telemetrii. Jedyne wywołania sieciowe to sprawdzenia tylko do odczytu za pomocą Twoich własnych git, gh i npm, które potwierdzają, czy skutek uboczny nastąpił. Rejestr zostaje w .git/better-workflows/.

A co z Codex, Gemini CLI lub Qwen Code?

Obsługiwały V5, które jest zamrożone. Core jest niezależny od hosta, a adaptery dla nich są planowane po alphie.

Wypróbuj w kilka sekund

Uruchomienie polecenia to nie dowód. Pliki są dowodem.

Uruchom demo bez Claude, potem zainstaluj plugin w jednym repozytorium i poproś o zmianę.

Zainstaluj w Claude CodeZobacz na GitHubie