AI 写了代码，又给自己判了"合格"——这种自证闭环，是 AI 辅助开发最大的隐患之一。claude-code-workflows 是一套面向 Claude Code 的开发工作流插件，它让 AI 对代码库的广泛探索始终聚焦在你已批准的结果上：先约定成果与排除项，把设计对照代码库检查，每个任务提交前逐层验证，最后再由独立的评审者审查完整实现。它的设计哲学可以浓缩为一句话：把"生成"与"验证"拆给不同的角色、不同的上下文，不让 AI 给自己打分。

问题起点：AI 不是不会探索，而是不会收敛

官方 README 开篇就点破了这个矛盾：

Claude Code can explore a codebase deeply. On non-trivial work, the harder problem is convergence.

翻译过来：AI 擅长把代码库翻个底朝天，但在非平凡任务上，真正难的是收敛——它可能在设计账户找回功能时，顺手发现 token 处理的某个不一致，然后大半篇幅都花在那里，而你要的找回行为反而含糊了。

除了方向漂移，还有两个更隐蔽的风险：

• 上下文自我偏见：同一个会话里，AI 既写了代码又评判代码。它记得自己的推理过程，倾向于为自己的选择找理由，而不是寻找反例。
• "测试通过"陷阱：项目对 code-reviewer 的定义里有一句话说得非常直白——一个通过的测试运行，只能证明"测试和代码彼此一致"，不能证明其中任何一方是对的。自己写测试、自己跑、自己宣布成功，本质上是自证。

核心解法：角色分离 + 上下文隔离

claude-code-workflows 的答案不是"写更长的提示词"，而是组织结构：把一次开发拆成多个专职子代理（subagent），每个角色只做一件事，且彼此看不到对方的内心独白。

项目 subagents-orchestration-guide 中有这样一条关键规则：

Each subagent invocation is afresh Agent tool call, isolating each phase's context; a SendMessage resume reuses the prior agent's context and breaks that isolation.

也就是说：每个阶段的子代理都是一次全新调用、全新上下文。执行者不知道评审者在期待什么，评审者也不记得自己是怎么实现的——隔离打破了"自我辩护"的心理惯性。

项目的角色分工大致如下（全部位于 agents/ 目录）：

这套编排的思想来源在 README 的 Design Rationale 一节中给出：外部反馈和新鲜上下文，比让同一个会话既生成又评判自己更可靠。

独立验证的三道防线

第一道：任务级质量门禁（每个任务、每次提交前）

实现阶段执行的是一个严格的四步循环（见 recipe-implement）：

1. 执行：task-executor 按任务文件实现，记录 diffBase；
2. 测试评审：若任务新增集成/E2E 测试，由独立的 integration-test-reviewer 检查测试是否真正观测到了它声称要证明的行为；
3. 质量门禁：quality-fixer 接手，先做stub 检测（把// TODO、返回占位值的空壳实现直接打回），再跑 lint、类型检查、构建、测试，修复范围内失败，直到pass；
4. 提交：只有门禁通过才允许 commit。

细节很见功力：quality-fixer 的 stub 检测被标注为BLOCKING — before any quality checks，因为通用的检查通过不能替代"实现真的完成了"——这是专门防"AI 写了个空壳却测试全绿"的。

第二道：设计文档的证据验证（写代码之前）

在 Medium/Large 规模的任务中，Design Doc 生成后、用户批准前，会先经过 code-verifier 的只读验证：把文档中的每一条关键声明（接口、契约、依赖、责任归属）对照代码库中最小的可判定证据范围核对，并给出严格的分类——

• match：证据支持该声明
• drift：描述已过时
• gap：依赖或目标缺失
• conflict：与观察到的行为矛盾
• unverified：证据不足，并明确写出"需要哪个可观察事实才能裁决"

注意最后一条：它不允许"我觉得没问题"，未验证就必须说清缺什么证据。随后的 document-reviewer 负责文档质量与下游可用性，design-sync 负责多份设计文档之间的冲突检测，acceptance-test-generator 则提前生成测试骨架，让"验收标准"在动手之前就变成可执行的证明义务。

第三道：实现完成后的独立评审（交付之前）

所有任务完成后，code-reviewer 与 security-reviewer 在独立上下文中并行审查完整实现，对照的是批准的 Design Doc / Work Plan，而不是之前的对话记录。

• code-reviewer 检查：验收标准是否逐条满足（file:line级证据）、是否存在"范围浪费"（scope_excess，即为了不存在的需求加的不必要机制）、契约与可靠性问题；
• security-reviewer 检查：可达信任模型下的具体可利用风险与缺失的防御控制，且明确排除"锦上添花式加固"——只报必须修的问题，避免评审者制造噪音。

但独立验证的最后一块拼图是Review Resolution（review-resolution.md）：评审发现的问题不会自动变成工作项。主会话（orchestrator）逐条裁决——属于已约定成果的才进入修复循环，其余的被显式拒绝并记录理由。这防止了另一个经典问题：AI 评审者过度敏感，无限扩大修改范围。

验证是"证据"，不是"观点"

贯穿整个项目的一条主线是：任何裁决都必须可追溯到可观察的证据。

• 所有子代理的最终输出都是结构化 JSON，发现项必须带file:line级位置和"最小充分修正"建议；
• verifier 在诊断流程中执行 Devil's Advocate 评估，主动追问："这个证据是否反而说明行为是正确的？有没有被忽略的反证？"——甚至规定：如果反证来自官方文档或语言规范，就自动削弱该结论的可信度；
• llm-friendly-context 技能要求每个交接都写明"读什么、做什么、什么算成功、哪些未决项会改变结果"，让下游消费者无需猜测。

这套机制背后的逻辑很简单：观点可以被立场污染，证据不能。

实战检验：一次被独立安全审查打回两次的改动

README 记录了一个真实案例：某项目的增量同步功能，42 个文件、横跨文件扫描/存储/CLI/MCP 四个面的大改动。独立的 security-reviewer两次把实现打了回去——

• 第一次：发现文件读取发生在校验之前；
• 第二次：发现通过符号链接父目录的"路径包含逃逸"漏洞。

如果没有独立的评审上下文，这两类问题很可能被实现者自己的会话"合理化"掉。这个例子说明独立验证的价值不在"多跑一遍"，而在于用一个新的、没有立场的视角去看最终产物。

什么时候该用它，什么时候不必

这个项目对自身成本是诚实的。README 明确建议：当成果和安全实现边界已经清晰时，直接用 Claude Code 即可；以下场景才值得启用工作流——

安装也很简单（需要先支持插件市场的 Claude Code 版本）：

/plugin install dev-workflows@claude-code-workflows /recipe-implement "Add rate limiting to the public API"

团队可以把它设为项目级插件，让所有贡献者共用同一套质量约束（完整文档）。

小结：验证是流程，不是口号

claude-code-workflows 的设计哲学，本质上是把人类团队里早已成立的经验——作者不应是自己工作的最终裁判——翻译成了 AI 可执行的流程结构：

1. 🎯先收敛再动手：成果与排除项在开始前就约定好，探索不能漂移方向；
2. 🧱角色分离 + 新鲜上下文：执行、质量门禁、评审分属不同子代理，打破自我辩护循环；
3. 🔍证据分类与结构化裁决：match/drift/gap/conflict/unverified、file:line证据、显式拒绝理由，让每次验证可追溯；
4. 🛡️独立安全审查：以可达信任模型为准绳，只报必须修的问题。

它不追求让 AI "一次做对"，而是接受"生成必有偏差"，然后用组织化、可审计的独立验证把偏差挡在提交与交付之前。对于正在把 AI 引入真实仓库的团队，这或许比"哪个模型更强"更值得思考。