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