收工
证据绑定文件
test、lint、typecheck 或 build 必须同时满足：通过、由它自己的 exit code 决定结果、运行期间没有文件变动、文件仍是它运行时的那一份，才算数。
可选
exact：只认完整命令，cwd指定它必须在哪里运行。scope（配合exact）：指定目录以外的改动不会让结果过期。ignore（整个 policy）：检查自己产生的输出（例如 coverage）不算改动。
V6 Corepre-alpha
证据要新，才算完成。
证据要新，才算完成。
结果不明，就先停下。
一个 Claude Code 插件：不让 AI agent 拿过期的绿灯收工，也不让它重复或叠加从未看到结果的副作用。它能做什么，由你写的 policy 文件决定，绝不由 prompt 决定。
- 证据对应当前文件
- 副作用最多一次
- Policy，而非 prompt
- 不明即停
- claude 修复
sum.mjs里的 bug，不用重跑测试 - test
node --test在文件a1f3上通过 - editagent 修改
sum.mjs，文件变为9c07 - stop“完成了，测试都通过。”
- bw退回：
test上次通过是在a1f3，之后文件已经改动。 - testagent 重跑
node --test：1 个失败，修复后在b2e8上通过 - push
git push在推送成功之后超时 - pushagent 重试
git push - bw拒绝：
git-push在这个 commit 上已经成功过。
SENT BACKCore 两次拦下 agent：一次是拿旧的通过结果收工，一次是再次 push。两次都附上原因退回。
Core 检查了什么
拦下 2 次 · 0 次假完成- Policy来自 .better-workflows/policy.jsonPASS
- 证据test 对应当前的文件BLOCKED
- 重跑test 在 b2e8 上通过PASS
- 副作用git-push，第一次PASS
- 最多一次同一个 push、同一个 commitBLOCKED
节选自仓库中的 stale-green 演示，tree 编号仅为示意。无需 Claude，几秒即可自己运行完整版。
- 1,576行内核代码上限 3,000 行
- 38项测试每道关卡都写明它防止的失败
- 0个运行时依赖只需要 Node.js 和 Git
- 6个 Claude Code hookSessionStart、PreToolUse、PostToolUse(Failure) 和 (Subagent)Stop；无需服务器或账号
- 4条 CI 流水线macOS 和 Linux × Node 22、24
- 41种语言本网站和 README 均支持
01原则PRINCIPLES
三条规则，模型越强越有用。
模型越强，一次会话写的代码越多，自己运行的命令也越多。这三条规则不依赖 agent 小心谨慎，无论它说什么都成立。
RULE 01
Prompt 不是授权
agent 能否 push、merge、release、publish，由它无法修改的 policy 文件决定。在 prompt 里怎么请求都没用。
RULE 02
证据绑定文件
测试通过只对它运行时的那一份文件有效。改一行，那次通过就不算了。
RULE 03
不明就停，不猜
结果不明的副作用会拦下之后所有副作用，直到向 provider 核实，或由人结案。
WITHOUT vs WITH同一个会话
| 场景 | 只有 agent | 加上 Core |
|---|---|---|
| 测试通过后又改了文件 | “测试都通过。” | 退回，在当前文件上重跑。 |
npm test | tail | 算作绿灯；但 exit code 属于 tail。 | 永远不算；收工时会说明原因。 |
| 只跑一个 spec 文件代替整套 | 算作“测试通过”。 | 设置 exact 后只认完整命令。 |
| push 成功后才超时 | 再 push 一次。 | 同一个 commit 的同一个 push 会被拒绝。 |
| Prompt 写着“你可以发布” | 直接发布。 | 由 policy 决定：allow、ask 或 deny。 |
AUTHORITY授权从哪里来
- L1policy.json来源
由人编写和修改。Core 会拒绝 agent 直接修改它。
- L2Claude Code 权限
依然有效。policy 中的
allow绝不会给出比 Claude Code 更多的权限。 - L3Core hooks
在每条命令、每次修改、每次收工时执行 policy。
- L4Prompt无
描述目标，不带任何授权。
02工作原理HOW IT WORKS
六个 hook，一本账存在 .git 里。
Core 运行在 Claude Code 自带的 hooks 里。无需启动服务、没有服务器、无需账号；状态存放在每个仓库的 .git/better-workflows/ 中。
HOOKShooks
- SessionStart：告诉 agent 哪些检查必须通过、哪些副作用尚未结案；policy 无效，或需要
gh却无法使用时发出警告。 - PreToolUse：对每个副作用决定 allow、ask 或 deny，并拒绝修改 policy 和账本。
- PostToolUse：记录每次检查运行在哪个 Git tree 上，以及每个副作用的 exit code。
- Stop：文件有改动，且必要的检查缺失、失败或已过期时，附上原因把 agent 退回一次；下一次只警告。
- bw status（是命令，不是 hook）：把同样的状态展示给你。
副作用
最多一次，不明就停
push、创建和合并 PR、release、发布软件包，以及你自定义的类型，都需要 policy 给出 allow。只有 exit code 0 才算确定的结果。
用于核实不明结果的只读查询
git ls-remotegh pr list / viewgh release viewnpm view
RULES始终成立的规则
- R1
policy 无效时，拒绝所有副作用，而不是回退到默认值。
- R2
权限过期后回退为 ask。只有人能通过修改 policy 来延长。
- R3
Core 读不懂的命令（例如
eval、sh -c）一律视为 opaque，交由你决定。 - R4
账本只能追加、以哈希链接；
bw verify能检测被修改或删除的条目以及写了一半的最后一行，但检测不到从末尾整条截掉的条目。
03支持范围HOSTS
先支持 Claude Code。
Core 本身与 host 无关，每个 host 只需要一层小的适配器。Claude Code 是第一个，也是目前唯一支持的。
| Host | macOS | Linux | Windows |
|---|---|---|---|
| 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，以及支持插件的 Claude Code。
- 1
Clone Core
每台机器一次。如果这台机器运行过 V5，先把
~/.better-workflows重命名为~/.better-workflows-V5，并让SBW_STATE_ROOT指向它。 - 2
添加插件
在每个仓库中用
--scope local安装，不会写入你要提交的文件。 - 3
编写 policy
bw init会生成.better-workflows/policy.json。提交它，大家就使用同一套规则。 完整教程涵盖自定义检查、副作用以及结果不明的处理。 快速入门
Claude Code
git clone https://github.com/stephen-taipei/better-workflows ~/.better-workflowsclaude plugin marketplace add ~/.better-workflows/packages/bw-coreclaude plugin install better-workflows-core@better-workflows --scope localnode ~/.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时，只跑了一部分也会拦下 - 用管道或
|| true掩盖失败 - 重复 push、merge、release 或 publish
- 前一个副作用结果不明时又执行新的副作用
- agent 直接修改自己的 policy 或账本
做不到
视野之外
- 看到脚本内部的副作用，除非 policy 点名了那个脚本
- 判断你的测试是否足够好
- 构建依赖图：
scope必须列出检查依赖的所有内容 - 把被 Git 忽略的文件算进证据
交给你
由人做的决定
- 为一个无法读回结果的副作用结案
- 让权限在
expiresAt之后继续有效 - 决定
scope覆盖哪些内容 - 判断会话是否在原地打转
Core 能拦下上面列出的错误。它能否在长任务中减少返工或错误决策，尚未经过测量；当前的自用期正是为此。
- B1shell 解析器不再扩充：读不懂的命令在运行前一律询问，藏在
eval或sh -c里的测试永远不算证据。 - B2Core 只统计会话的进展。是否在收敛，由 agent 或你来判断。
- B3PR 和 release 依靠
gh对账；没有它，结果会一直不明，直到你手动结案。
06项目状态STATUS
项目进展到哪里了。
V6 用一个小巧的 Core 取代 V5 的工作流引擎。条件达成时才定日期。
DONE 已冻结
V5.0 RC1
tag V5.0.rc1
多 host 工作流引擎。冻结在
frozen/v5分支，不再开发。NOW 进行中
V6 Core pre-alpha
packages/bw-core
Claude Code hooks、证据 scope，在两个仓库上自用。
NEXT 自用期之后
V6 Core alpha
第一个打 tag 的版本
等自用期证明确实能拦下问题、且误拦很少，才会发布。之后以小型适配器支持更多 host。
STATEMENT声明
PRE-ALPHA
Core 现在就能用，并运行在维护者自己的仓库上。alpha 之前 policy 格式仍可能变化。
这里的一切都免费、开源。没有付费版、账号或遥测。
LICENSING许可证
| 部分 | 许可证 | 状态 |
|---|---|---|
V6 Core（packages/bw-core） | Apache-2.0 | 活跃 |
| 网站及仓库其余部分 | AGPL-3.0-only | 活跃 |
| V5 插件 | AGPL-3.0-only在 frozen/v5 | 已冻结 |
07文档DOCS
所有内容都在仓库里。
指南有英文和繁体中文两个版本。本站的每种语言在 GitHub 上都有一份简短的 README。
08常见问题FAQ
常见问题，直接回答。
还有其他问题？在 GitHub 上提 issue。 GitHub Issues
会让 Claude Code 变慢吗？
处理检查或副作用的 hook 会用 Git 计算一次工作区的哈希，普通大小的仓库只需几毫秒。超大仓库每次这类调用会多花一些时间。
会不会一直把 agent 退回，卡住出不来？
退回时会附上原因，以及这次会话到目前的情况：运行次数、连续失败次数、已被退回的次数。agent 可以据此停下来，直接告诉你哪一项检查一直失败。
agent 能把它关掉吗？
不能直接关闭。Core 会拒绝 agent 修改 policy 和账本，也会拒绝 bw init 和手动结案。卸载插件，或以迂回方式修改这些文件，则由 Claude Code 自身的权限规则把关，所以请保持这些确认提示开启。
会把数据发送到别处吗？
没有服务器，也没有遥测。唯一的网络调用，是用你自己的 git、gh 和 npm 做只读查询，确认副作用是否发生。账本保存在 .git/better-workflows/。
Codex、Gemini CLI 或 Qwen Code 呢？
它们运行的是已冻结的 V5。Core 与 host 无关，alpha 之后计划为它们开发适配器。
09赞助SPONSOR
支持 Better Workflows。
以 USDT（TRC20）一次性赞助
赞助用于开源维护、英文与繁体中文文档以及网站托管。它不提供会员资格，也不换取路线图优先级或技术支持。
USDT · TRON (TRC20)
TGuMUi1d8MoBQcuFrGJZnu4JrbaeP3wy9a