myclawbbbot-cyber/claude-agent-gates

# claude-agent-gates **一个用于多 agent Claude Code 的治理层 - 而不是又一个 agent 集合。** 大多数 agent 工具包提供的是*更多的构建者*。以构建者为主的配置，其失败原因往往不是“agent 不够多”，而是同一个模型既负责编写工作，又负责审查工作，最后还宣布工作完成。自我评分的工作会不断累积偏差：审查者总能找到理由证明输出没问题，边缘情况无人测试，一份亮起绿灯的自我报告掩盖了真实的缺陷。本工具包正是旨在阻止这种情况的治理层。 三大支柱： 1. **举证责任质量门** (`qa-gate`) - 默认 FAIL，只有当评审者提供了能够自行复现的证据时才能获得分数，设有严格的通过阈值，且低于该阈值时强制驳回。它没有写权限；它只负责评审，从不负责修复。 2. **红队升级契约** (`critic`) - 一个常驻的“魔鬼代言人”，其*重大*异议不能被悄悄驳回：它们会逐字升级给人类处理。 3. **针对评审者本身的回归测试套件** (`eval/`) - 因为评审者本质上是一个 prompt，而 prompt 就是生产代码。包含黄金任务、grep 断言以及一个在分数下降时会阻断发布的评分历史记录。 ## 客观定位 这是一个治理 / 严格性控制层。它与下文提到的工具是组合关系，而不是替代关系。 | 如果你想要... | 使用 | 本工具包反而会带给你 | | --- | --- | --- | | 一个包含大量即用型构建者 agent 的大型库 | agent 集合 (例如 `wshobson/agents`) - 他们在这方面做得很好 | 一个能够审查这些 agent 产出的门控 | | 一个功能齐全的评估 / 红队框架 | `promptfoo` - 更重、功能更丰富，是进行严肃评估的合适工具 | 一个专为你的 *judge* prompt 设计的精简、零依赖回归测试套件 | | 更多的 agent 来做更多的工作 | - | 更少的 agent，但需达到更严格的标准 | 如果你已经有了喜欢的构建者 agent，请保留它们。只需将此门控指向它们的输出即可。 ## 包含内容 ``` .claude/agents/ qa-gate.md # the burden-of-proof quality gate (read-only judge) critic.md # the standing red team, with the verbatim-escalation contract code-reviewer.md # a neutral example agent to adapt fact-checker.md # a neutral example agent to adapt docs/GOVERNANCE.md # the five load-bearing rules + the literature behind them scripts/ review.sh # run the gate against a diff/dir/file, exit on the verdict verdict.sh # parse a review, exit 0/1 (fail-closed), escalate after 2 FAILs verdict_test.sh # self-test battery for verdict.sh eval/ agent_eval.sh # the regression harness for judgment agents golden/ # neutral golden tasks (planted bug, clean pass, fabricated stat) examples/demo.md # a full build -> gate -> bounce -> fix -> PASS walkthrough ``` ## 60 秒快速入门 要求 [Claude Code CLI](https://docs.claude.com/en/docs/claude-code) 已加入你的 `PATH` 中。 ``` # 1. Clone it. The judges live in .claude/agents/, so Claude Code picks them up # automatically when you run inside the repo. git clone https://github.com/myclawbbbot-cyber/claude-agent-gates cd claude-agent-gates # 2. Run the gate against something. Here, one of the golden fixtures with a # planted off-by-one bug and a self-report that claims all tests are green: scripts/review.sh eval/golden/qa-gate/gt1-planted-bug \ "implement page_count; the final partial page must be counted" # -> the gate reproduces the spec, constructs the case the shipped tests miss, # prints a scorecard, and exits 1 with VERDICT: FAIL. # 3. Run the same gate against a genuinely clean deliverable: scripts/review.sh eval/golden/qa-gate/gt2-clean-pass \ "implement clamp into an inclusive range" # -> VERDICT: PASS, exit 0. ``` 这就是整个循环：`review.sh` 会返回一个 shell 退出码，因此你可以据此对 commit 或 CI 步骤进行门控： ``` scripts/review.sh ./src "the goal this change must satisfy" || exit 1 ``` 为了在修改 prompt 时保持 *judges* 的客观公正，请运行回归测试套件： ``` bash eval/agent_eval.sh qa-gate # runs every golden task, greps the assertions, bash eval/agent_eval.sh critic # appends a score line to eval/baselines/.tsv ``` 在修改 judge 之前先运行它以获取基线，修改后再运行以进行比较。总分下降将阻断更改 - 参见 `docs/GOVERNANCE.md`。 断言以 `MUST:` / `MUST_NOT:` 的形式存在于每个任务的 `assert.txt` 中。如果断言中包含 `VERDICT:`，它将仅与审查提取出的最终裁决词进行匹配（即最后一个 `VERDICT: PASS|FAIL`，其解析方式与 `verdict.sh` 相同），而不匹配原始记录 - 这样一来，如果 judge 在其叙述文字中引用了断言文本，也不会导致误匹配。所有其他模式将匹配整个记录。 门控自身的解析逻辑也经过了测试，且无需消耗任何模型调用： ``` bash scripts/verdict_test.sh # asserts verdict.sh's fail-closed + escalation behavior ``` ## 关于约束力来源的说明 这两大支柱的执行力度并不相同，有必要在此明确指出。 **门控** 具有机制上的强制力：`verdict.sh` 是一个脚本，它会以失败为默认结果 (fail closed) 并返回你的 CI 将严格服从的真实退出码。而 **critic 的逐字升级契约** 是一种 *prompt 层面* 的协议 - 它存在于 agent 的指令和 `docs/GOVERNANCE.md` 中，但本工具包中没有任何东西能强制编排器去遵守它。它是你主动采纳的一项纪律，而不是由脚本执行的门控。请将其视作如此。 ## Claude Code 如何发现 agent 这些 judge 存放在仓库根目录下的 `.claude/agents/` 中。Claude Code 会从你正在工作的项目的 `.claude/agents/` 目录中发现项目作用域的 agent，因此**只需克隆仓库并从内部运行脚本即可满足需求** - 无需安装步骤，也无需将文件复制到你的家目录中。正是出于这个原因，脚本在运行 `claude` 时会将该仓库根目录设为工作目录。 如果你希望在*每个*项目中都能使用这些 agent，请将它们复制到你的用户级 agent 目录 (`~/.claude/agents/`) 中。 ## 无头模式 / CI 用法 默认情况下，脚本在运行 judge 时，只允许其使用进行读取/验证所需的相关工具白名单 (`--allowedTools "Bash Read Grep Glob"`)，因此无头运行绝不会一刀切地关闭权限检查 - 它只会精确授予 judge 用于复现和验证的工具。 如果你需要完全无人值守地运行，并希望完全跳过权限提示，可以设置 `GATES_YOLO=1`，这会添加 `--permission-mode bypassPermissions` 参数。这将在关闭权限检查的情况下运行 agent - **请仅在你信任的环境中使用，并自负风险。** 它永远不是默认选项。 其他配置项（均为可选）： - `GATES_REVIEW_AGENT` - 指定 `review.sh` 使用的 agent（默认为 `qa-gate`；你可以将其指向一个更严格或使用不同模型的门控，以获取跨家族的第二意见）。 - `GATES_CLAUDE_BIN` - 如果 `claude` 二进制文件不在 `PATH` 中，指定其路径。 - `GATES_STATE_DIR` - 存储 FAIL 连续记录和上次审查结果的位置（默认为 `.gates/`）；为每个交付物指定其专属目录，以实现针对单个交付物的连续记录追踪。 ## 许可证 MIT - 参见 [LICENSE](LICENSE)。

标签：AI治理, Cutter, LLM评估, LNA, Ollama, 多智能体, 防御加固