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 對帳；沒有它，結果會一直未明，直至你手動結案。

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 不綁定任何 host，alpha 之後會計劃為它們做 adapter。

幾秒即可試用

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

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

安裝到 Claude Code前往 GitHub