Better WorkflowsV6
Українська
V6 Corepre-alpha

Доказ має бути свіжим.
Невідомо — стоп.

Плагін для Claude Code, який не дає AI-агенту завершити роботу на застарілому зеленому тесті, а також повторювати чи накладати побічні дії, результату яких він не побачив. Що йому дозволено, визначає policy-файл, який пишете ви, а не промпт.

  • Актуальні докази
  • Не більше одного разу
  • Policy, а не промпт
  • Fail-closed
Встановити для Claude Code Як він зупиняє GitHub

stale-green · застарілий зелений тест, потім повторний push

demo
  1. claude виправ баг у sum.mjs, тести перезапускати не треба
  2. testnode --test проходить на файлах a1f3
  3. editагент редагує sum.mjs, тепер файли — 9c07
  4. stop«Готово. Тести проходять.»
  5. bwПовернуто: test востаннє пройшов на a1f3; відтоді файли змінилися.
  6. testагент перезапускає node --test: 1 падіння, виправляє, проходить на b2e8
  7. pushgit push завершується тайм-аутом уже після того, як push пройшов
  8. pushагент повторює git push
  9. bwВідхилено: git-push уже успішно виконано на цьому коміті.

SENT BACKCore двічі зупинив агента: раз — коли той хотів завершити на старому успішному запуску, раз — коли хотів повторно зробити push. Обидва рази його повернули з поясненням причини.

Що перевірив Core

2 ЗУПИНКИ · 0 ХИБНИХ «ГОТОВО»
  1. Policyз .better-workflows/policy.jsonPASS
  2. Доказитест на файлах у поточному станіBLOCKED
  3. Перезапусктест проходить на b2e8PASS
  4. Діяgit-push, упершеPASS
  5. Не більше разутой самий push, той самий комітBLOCKED

Скорочено з демо stale-green у репозиторії; ідентифікатори tree умовні. Запустіть повне демо самі за кілька секунд, без Claude.

01ПринципиPRINCIPLES

Три правила, що корисніші з кожною сильнішою моделлю.

Сильніший агент пише більше коду за сесію і сам запускає більше команд. Ці правила не залежать від обережності агента; вони діють, хоч би що він казав.

WITHOUT vs WITHта сама сесія

СитуаціяЛише агентЗ Core
Тести пройшли, потім змінився файл«Тести проходять.»Повертають, щоб перезапустити на поточних файлах.
npm test | tailВважається зеленим; exit code належить tail.Ніколи не зараховується; Stop пояснює чому.
Один spec-файл замість усього наборуВважається «тести проходять».З exact зараховується лише повна команда.
Push завершується тайм-аутом, хоча пройшовPush-ить знову.Той самий push на тому самому коміті відхиляється.
У промпті сказано «можеш публікувати»Публікує.Вирішує policy: allow, ask або deny.

AUTHORITYзвідки беруться повноваження

  1. L1
    policy.json

    Пише та змінює людина. Core відхиляє прямі редагування його агентом.

    ДЖЕРЕЛО
  2. L2
    Дозволи Claude Code

    Діють і далі. allow у policy ніколи не дає більше, ніж дозволив би Claude Code.

  3. L3
    Hooks Core

    Застосовують policy до кожної команди, кожного редагування і кожної зупинки.

  4. L4
    Промпт

    Описує мету. Не несе жодних повноважень.

    НЕМАЄ

02Як це працюєHOW IT WORKS

Шість hooks, один журнал у .git.

Core працює всередині власних hooks Claude Code. Нічого не треба запускати, без сервера, без облікового запису; стан зберігається в .git/better-workflows/ кожного репозиторію.

HOOKShooks

  1. SessionStart: повідомляє агенту, які перевірки мають пройти і які побічні дії ще не вирішені, та попереджає, якщо policy недійсна або gh потрібен, але непридатний до використання.
  2. PreToolUse: дозволяє, запитує або відхиляє кожну побічну дію і не дає редагувати policy та журнал.
  3. PostToolUse: записує кожну перевірку разом із Git tree, на якому вона запускалася, і кожну побічну дію з її exit code.
  4. Stop: якщо файли змінилися, а обов'язкова перевірка відсутня, не пройшла або застаріла, один раз повертає агента з поясненням причини; наступного разу лише попереджає.
  5. bw status (команда, а не hook): показує вам той самий стан.
STOP

Завершення

докази прив'язані до файлів

Test, lint, typecheck чи build зараховується, лише якщо він пройшов, результат визначив його власний exit code, під час запуску не змінився жоден файл, а файли досі точно такі, на яких він запускався.

Необов'язково

  • exact: зараховується лише повна команда, а cwd задає, де її треба запускати.
  • scope (разом з exact): зміна поза вказаними каталогами залишає результат актуальним.
  • ignore (для всієї policy): вивід, який пише перевірка, як-от coverage, не вважається зміною.
PRETOOLUSE

Побічні дії

не більше разу, невідоме зупиняє

Push, створення та merge PR, релізи, публікація пакетів і ваші власні типи дій потребують allow у policy. Відомим результатом вважається лише exit code 0.

Перевірки лише на читання, якими з'ясовують невідомий результат

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

RULESправила, що діють завжди

  • R1

    Невалідна policy відхиляє всі побічні дії, а не повертається до типових значень.

  • R2

    Дозвіл, термін якого минув, повертається до ask. Продовжити його може лише людина, відредагувавши policy.

  • R3

    Команди, які Core не може розібрати, як-от eval чи sh -c, вважаються непрозорими, і про них запитують.

  • R4

    Журнал лише доповнюється і зв'язаний ланцюжком хешів; bw verify виявляє змінені чи видалені записи та недописаний останній рядок, але не цілі записи, відрізані з кінця.

03ХостиHOSTS

Спершу Claude Code.

Core не прив'язаний до хоста; кожному хосту потрібен невеликий адаптер. Claude Code — перший і поки єдиний підтримуваний.

Підтримка хостів і операційних систем
ХостmacOSLinuxWindows
Claude CodeПерший хостПідтримується, тестується в CIПідтримується, тестується в CIНе тестується
CodexЛише V5, замороженоЗапланованоЗапланованоЗаплановано
Gemini CLIЛише V5, замороженоЗапланованоЗапланованоЗаплановано
Qwen CodeЛише V5, замороженоЗапланованоЗапланованоЗаплановано

CI запускає Core на кожному pull request.macOS 15 і Ubuntu 24.04, Node 22.23.3 і 24.21.0.

04ПочатиGET STARTED

Три команди, потім попросіть зміну.

Потрібні Node.js 22.14 або новіший, Git і Claude Code з підтримкою плагінів.

  1. 1

    Клонуйте Core

    Один раз на машину. Якщо тут уже працювала V5, спершу перемістіть ~/.better-workflows до ~/.better-workflows-V5 і спрямуйте SBW_STATE_ROOT на цей каталог.

  2. 2

    Додайте плагін

    Встановлюйте його для кожного репозиторію з --scope local, щоб нічого не записувалося у файли, які ви комітите.

  3. 3

    Напишіть policy

    bw init створює .better-workflows/policy.json. Закомітьте його, щоб усі мали однакові правила.

  4. Повний посібник описує власні перевірки, побічні дії та невідомі результати. Початок роботи

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

Необов'язково: запустіть обидва сценарії без Claude за кілька секунд.

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

Потім спробуйте

Зміни один рядок у цьому репозиторії й не запускай тести.

Коли Claude Code спробує завершити, його повернуть і скажуть, якої перевірки бракує.

05МежіLIMITS

Що він зупиняє і чого не бачить.

Перевірка корисна, лише якщо ви знаєте її межі.

Зупиняє

Помилки, які видно

  • Завершення на застарілому чи невдалому запуску тестів або на частковому, коли перевірку позначено exact
  • Pipe або || true, що приховує збій
  • Повторний push, merge, реліз чи публікацію
  • Побічні дії, поки результат попередньої невідомий
  • Пряме редагування агентом власної policy чи журналу

Не робить

Поза полем зору

  • Не бачить побічних дій усередині скрипта, якщо policy не називає цей скрипт
  • Не оцінює, чи достатньо добрі ваші тести
  • Не будує граф залежностей: scope має називати все, від чого залежить перевірка
  • Не враховує файли, ігноровані Git, як частину доказів

Залишає вам

Рішення, які ухвалює людина

  • Вирішити долю побічної дії, результат якої неможливо прочитати
  • Продовжити дозвіл після expiresAt
  • Обрати, що охоплює scope
  • Визначити, коли сесія ходить по колу
Core блокує помилки, наведені вище. Чи зменшує він переробки або хибні рішення на довгих задачах, не вимірювалося; саме для цього й потрібен поточний період власного використання.
  1. B1Парсер shell не розширюється: про команду, яку він не може розібрати, запитують до її запуску, а тест, схований усередині eval чи sh -c, ніколи не зараховується як доказ.
  2. B2Core лише рахує, як іде сесія. Чи вона збігається до результату, судити агенту або вам.
  3. B3Pull request і релізи звіряються через gh; без нього вони лишаються невідомими, доки ви їх не вирішите.

06СтатусSTATUS

Де зараз проєкт.

V6 замінює workflow-рушій V5 невеликим ядром. Дати з'являються, коли умови виконано.

  1. DONE Заморожено

    V5.0 RC1

    tag V5.0.rc1

    Багатохостовий workflow-рушій. Заморожено в гілці frozen/v5; нова робота не ведеться.

  2. NOW У роботі

    V6 Core pre-alpha

    packages/bw-core

    Hooks Claude Code, scope доказів, власне використання у двох репозиторіях.

  3. NEXT Після власного використання

    V6 Core alpha

    перший реліз із тегом

    Вийде, щойно період власного використання покаже реальні перехоплення і мало хибних блокувань. Інші хости з'являться як невеликі адаптери.

STATEMENTзаява

PRE-ALPHA

Core уже можна використовувати, і він працює у власних репозиторіях мейнтейнера. Формат policy ще може змінитися до alpha.

Усе тут безкоштовне і з відкритим кодом. Немає платного тарифу, облікового запису чи телеметрії.

LICENSINGліцензування

ліцензування
ЧастинаЛіцензіяСтан
V6 Core (packages/bw-core)Apache-2.0активна
Сайт і решта репозиторіюAGPL-3.0-onlyактивна
Плагін V5AGPL-3.0-onlyу frozen/v5заморожено

07ДокументаціяDOCS

Усе є в репозиторії.

Посібники написано англійською та традиційною китайською. Для кожної мови цього сайту є короткий README на GitHub.

08FAQFAQ

Поширені запитання, прямі відповіді.

Щось інше? Відкрийте issue на GitHub. GitHub Issues

Чи сповільнює він Claude Code?

Hooks, що обробляють перевірку чи побічну дію, обчислюють хеш робочого дерева через Git, що в звичайному репозиторії займає мілісекунди. Дуже великі репозиторії платять більше за кожен такий виклик.

Чи не застрягне він, без кінця повертаючи агента?

Він повертає агента з причиною і з тим, як ішла сесія досі: кількість запусків, невдачі поспіль, скільки разів уже повертали. Тоді агент може зупинитися і прямо сказати вам, яка перевірка постійно не проходить.

Чи може агент його вимкнути?

Не напряму. Core відхиляє редагування агентом policy та журналу, а також bw init і ручне вирішення долі дії. Видалення плагіна чи зміна цих файлів обхідними шляхами підпорядковується власним правилам дозволів Claude Code, тож не вимикайте ці запити.

Чи надсилає він щось кудись?

Немає ні сервера, ні телеметрії. Єдині мережеві виклики — це перевірки лише на читання вашими власними git, gh і npm, щоб підтвердити, чи відбулася побічна дія. Журнал лишається в .git/better-workflows/.

А як щодо Codex, Gemini CLI чи Qwen Code?

Вони працювали з V5, яку заморожено. Core не прив'язаний до хоста, і адаптери для них заплановано після alpha.

Спробуйте за кілька секунд

Запуск команди — не доказ. Доказ — це файли.

Запустіть демо без Claude, потім встановіть плагін в один репозиторій і попросіть зміну.

Встановити для Claude CodeПереглянути на GitHub