Better WorkflowsV6
繁體中文
V6 Corepre-alpha

證據要新，才算完成。
結果不明，就先停下。

一個 Claude Code plugin：不讓 AI agent 拿過期的綠燈收工，也不讓它重複或疊加沒看到結果的副作用。它能做什麼，由你寫的 policy 檔決定，永遠不由 prompt 決定。

  • 證據對應現在的檔案
  • 副作用最多一次
  • Policy，不是 prompt
  • 不明就停
安裝到 Claude Code 看它怎麼擋 GitHub

stale-green · 過期的綠燈，接著一次重試的 push

demo
  1. claude 修正 sum.mjs 的錯誤，不用重跑測試
  2. testnode --test 在檔案 a1f3 上通過
  3. editagent 修改 sum.mjs，檔案變成 9c07
  4. stop「完成了，測試都通過。」
  5. bw退回：test 上次通過是在 a1f3，之後檔案已經改過。
  6. testagent 重跑 node --test：1 個失敗，修好後在 b2e8 通過
  7. pushgit push 在推送成功之後逾時
  8. pushagent 重試 git push
  9. bw拒絕：git-push 在這個 commit 已經成功過。

SENT BACKCore 擋下 agent 兩次：一次是拿舊的通過結果收工，一次是重複 push。兩次都附上原因退回。

Core 檢查了什麼

擋下 2 次 · 0 次假完成
  1. Policy來自 .better-workflows/policy.jsonPASS
  2. 證據test 對應現在的檔案BLOCKED
  3. 重跑test 在 b2e8 通過PASS
  4. 副作用git-push，第一次PASS
  5. 最多一次同一個 push、同一個 commitBLOCKED

節錄自 repository 裡的 stale-green demo，tree 編號為示意。不需要 Claude，幾秒鐘就能自己跑完整版。

01原則PRINCIPLES

三條規則，模型越強越有用。

模型越強，一次 session 寫的程式越多，自己跑的指令也越多。這三條規則不靠 agent 小心，不管它說什麼都成立。

WITHOUT vs WITH同一個 session

情境只有 agent加上 Core
測試通過後又改了檔案「測試都通過。」退回，在現在的檔案上重跑。
npm test | tail算綠燈；但 exit code 是 tail 的。永遠不算；收工時會說明原因。
只跑一個 spec 檔頂替整套算「測試通過」。設了 exact 就只認完整指令。
push 成功後才逾時再 push 一次。同一個 commit 的同一個 push 會被拒絕。
Prompt 寫「你可以發佈」直接發佈。由 policy 決定：allow、ask 或 deny。

AUTHORITY授權從哪裡來

  1. L1
    policy.json

    由人撰寫與修改。Core 會拒絕 agent 直接修改它。

    來源
  2. L2
    Claude Code 權限

    照樣有效。policy 的 allow 絕不給出比 Claude Code 更多的權限。

  3. L3
    Core hooks

    在每個指令、每次修改、每次收工時執行 policy。

  4. L4
    Prompt

    描述目標，不帶任何授權。

    無

02運作方式HOW IT WORKS

六個 hook，一本帳存在 .git 裡。

Core 跑在 Claude Code 自己的 hooks 裡。不用啟動服務、沒有伺服器、不用帳號；狀態存在每個 repository 的 .git/better-workflows/。

HOOKShooks

  1. SessionStart：告訴 agent 哪些檢查必須通過、哪些副作用尚未結案；policy 無效，或需要 gh 卻無法使用時發出警告。
  2. PreToolUse：對每個副作用決定 allow、ask 或 deny，並拒絕修改 policy 與帳本。
  3. PostToolUse：記錄每次檢查跑在哪個 Git tree 上，以及每個副作用的 exit code。
  4. Stop：檔案有變動，而必要的檢查還缺、失敗或已過期時，附上原因把 agent 退回一次；下一次只警告。
  5. bw status（是指令，不是 hook）：把同樣的狀態給你看。
STOP

收工

證據綁定檔案

test、lint、typecheck 或 build 要同時符合：通過、由它自己的 exit code 決定結果、執行期間沒有檔案變動、檔案仍然是它跑的那一份，才算數。

可選

  • exact：只認完整指令，cwd 指定它要在哪裡執行。
  • scope（搭配 exact）：指定目錄以外的變更不會讓結果過期。
  • ignore（整份 policy）：檢查自己產生的輸出（例如 coverage）不算變更。
PRETOOLUSE

副作用

最多一次，不明就停

push、建立與合併 PR、release、套件發佈，以及你自訂的種類，都要 policy 給 allow。只有 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）一律當成 opaque，交給你決定。

  • R4

    帳本只能附加、以 hash 串接；bw verify 能偵測被修改或刪除的紀錄與寫到一半的最後一行，但偵測不到從尾端整筆截掉的紀錄。

03支援範圍HOSTS

先支援 Claude Code。

Core 本身不綁特定工具，每個 host 只需要一層小的 adapter。Claude Code 是第一個，也是目前唯一支援的。

支援的 host 與作業系統
HostmacOSLinuxWindows
Claude Code第一個 host支援，CI 測試支援，CI 測試未測試
Codex僅 V5，已凍結規劃中規劃中規劃中
Gemini CLI僅 V5，已凍結規劃中規劃中規劃中
Qwen Code僅 V5，已凍結規劃中規劃中規劃中

每個 pull request 都會跑 Core 的 CI。macOS 15 與 Ubuntu 24.04，Node 22.23.3 與 24.21.0。

04開始使用GET STARTED

三行指令，然後請它改點東西。

需要 Node.js 22.14 以上、Git，以及支援 plugin 的 Claude Code。

  1. 1

    Clone Core

    每台機器一次。這台跑過 V5 的話，先把 ~/.better-workflows 改名為 ~/.better-workflows-V5，並把 SBW_STATE_ROOT 指向它。

  2. 2

    加入 plugin

    每個 repository 用 --scope local 安裝，不會寫進你要 commit 的檔案。

  3. 3

    寫 policy

    bw init 會建立 .better-workflows/policy.json。commit 它，大家就用同一套規則。

  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

接著試試看

幫我改這個 repository 的一行程式，不要跑測試。

Claude Code 想收工時會被退回，並告訴它缺了哪一項檢查。

05限制LIMITS

它擋得住什麼，看不到什麼。

知道邊界在哪裡，這道關卡才有用。

擋得住

看得到的錯誤

  • 拿過期或失敗的測試收工；檢查標成 exact 時，只跑一部分也擋
  • 用 pipe 或 || true 蓋掉失敗
  • 重複 push、merge、release 或 publish
  • 前一個副作用結果不明時又執行新的副作用
  • agent 直接修改自己的 policy 或帳本

做不到

看不到的範圍

  • 腳本裡的副作用，除非 policy 把那支腳本列為自訂動作
  • 判斷你的測試寫得夠不夠好
  • 建立相依關係：scope 要列出檢查依賴的所有目錄
  • 把 Git 忽略的檔案算進證據

交給你

由人決定的事

  • 結案一個查不到結果的副作用
  • 讓權限超過 expiresAt 繼續有效
  • 決定 scope 涵蓋哪些目錄
  • 判斷 session 是否在原地打轉
Core 擋得住上面列的錯誤。它能不能降低長任務的重工或錯誤決策，還沒有量測過；目前的自用期就是為了這件事。
  1. B1shell 解析器不再擴充：看不懂的指令執行前一律詢問，藏在 eval 或 sh -c 裡的測試永遠不算證據。
  2. B2Core 只統計 session 的進展，是否在收斂由 agent 或你判斷。
  3. B3PR 與 release 靠 gh 對帳；沒有 gh 時會維持不明，直到你手動結案。

06專案狀態STATUS

專案目前在哪裡。

V6 用一個小的 Core 取代 V5 的工作流引擎。條件達成才訂日期。

  1. DONE 已凍結

    V5.0 RC1

    tag V5.0.rc1

    多 host 的工作流引擎。凍結在 frozen/v5 分支，不再開發。

  2. NOW 進行中

    V6 Core pre-alpha

    packages/bw-core

    Claude Code hooks、證據 scope，在兩個 repository 上自用。

  3. NEXT 自用期之後

    V6 Core alpha

    第一個 tag 版本

    自用期證明真的擋下錯誤、而且誤擋夠少，才會發佈。之後再以小型 adapter 支援更多 host。

STATEMENT聲明

PRE-ALPHA

Core 現在就能用，並在維護者自己的 repository 上運作。alpha 之前 policy 格式仍可能調整。

這裡的一切都免費、開源。沒有付費方案、帳號或遙測。

LICENSING授權

授權
部分授權狀態
V6 Core（packages/bw-core）Apache-2.0使用中
網站與 repository 其他部分AGPL-3.0-only使用中
V5 pluginAGPL-3.0-only在 frozen/v5已凍結

07文件DOCS

所有文件都在 repository 裡。

教學有英文與繁體中文兩個版本。本站每種語言在 GitHub 上都有一份簡短的 README。

08常見問題FAQ

常見問題，直接回答。

還有其他問題？到 GitHub 開 issue。 GitHub Issues

會讓 Claude Code 變慢嗎？

處理檢查或副作用的 hook 會用 Git 計算一次工作目錄的 hash，一般大小的 repository 只要幾毫秒。非常大的 repository 每次這類呼叫會多花一些時間。

會不會一直把 agent 退回、卡住出不來？

退回時會附上原因，以及這個 session 到目前的狀況：跑了幾次、連續失敗幾次、已經被退回幾次。agent 可以據此停下來，直接告訴你是哪一項檢查一直失敗。

agent 能把它關掉嗎？

不能直接關。Core 會拒絕 agent 修改 policy 與帳本，也拒絕 bw init 與手動結案。移除 plugin，或用迂迴方式改這些檔案，則由 Claude Code 自己的權限規則把關，所以請保留那些確認提示。

會把資料傳到哪裡嗎？

沒有伺服器，也沒有遙測。唯一的網路呼叫，是用你自己的 git、gh、npm 做唯讀查詢，確認副作用有沒有發生。帳本留在 .git/better-workflows/。

Codex、Gemini CLI 或 Qwen Code 呢？

它們跑的是已凍結的 V5。Core 不綁特定工具，alpha 之後會規劃它們的 adapter。

幾秒鐘就能試

跑過指令不是證明，檔案才是。

先在沒有 Claude 的情況下跑 demo，再裝到一個 repository，請它改點東西。

安裝到 Claude Code前往 GitHub