Agent Workbench：多 Agent 协作开发工作流实践

本文介绍个人在 AI 辅助开发中逐步形成的一套多 Agent 协作工作流。它以 Claude Code 或 Pi 作为 Main，通过 Herdr 调度 Pi 子 Agent，并结合共享 Core 规则、可复用 Skills 和任务上下文产物，串联需求澄清、任务规划、代码实现、独立审查与最终验收，借助任务契约、决策记录、实现交接和开发者审阅让工作过程可追溯。

项目仓库： eteplus/agent-workbench

仓库维护共享 Core 规则、Claude Code / Pi Runtime 入口、Skills、任务模板和安装脚本；实际 Agent 调度依赖本机安装的 Herdr、Pi、模型 Provider 及相关工具，仓库只定义工作方式与集成约定，不包含独立的 Agent 调度服务。

这套方案来自日常开发中的持续探索，目前仍在演进，主要适配维护者现阶段的工具组合与工程习惯。本文侧重介绍设计思路与协作机制，读者可结合自身项目、工具链、权限模型和团队流程调整采用；具体安装、配置和使用细节以仓库文档为准。

1. 为什么需要 agent-workbench：不只关心产出，也关心理解与意图

多 Agent 可以并行研究、实现和审查，但也会带来新的工程管理问题：主控需要把任务拆成可执行单元，子 Agent 需要准确理解边界，开发者则需要清楚代码为何这样改、自动化决策是否偏离原始需求。

agent-workbench 用任务分级、角色分工、显式上下文契约和证据验收来承接这些责任，并针对开发者理解补充了三项机制：决策追踪、实现 Walkthrough 和按风险触发的人工 Developer Review。

三种 AI 技术债与工作流回应

图 1｜认知债务、理解债务和意图债务分别对应知识沉淀、Implementation Walkthrough、决策追踪与人工确认，并落到 overview.md、handoff.md 和 decisions.md 等可审阅产物。

这三种技术债是分析 AI 辅助开发风险的视角，并非仓库内置的三个独立模块或 Agent 角色；表中的映射来自当前 Core 规则对任务总览、决策记录、实现 Walkthrough、人工审阅和知识沉淀的定义。这些机制旨在降低技术债累积的概率，把重要上下文和责任边界显式化，方便开发者查找证据、提出修改并确认重要决定，但不会自动保证每位开发者理解所有变更，也不会代替产品负责人作出业务取舍。

2. 整体架构：Runtime 入口、共享 Core、Herdr 调度、Skills 与任务产物

agent-workbench 将工作流规则与 Agent Runtime 分开维护。Claude Code 或 Pi 都可以担任 Main；Core 定义统一的任务规则；Main 根据规则通过 Herdr 派发 Pi 子 Agent；Skills 提供可复用的专项能力；执行报告写入目标项目中的任务目录。

2.1 Runtime 入口：Claude Code 与 Pi 共用 /workflow

两个入口读取 AGENT_WORKBENCH_ROOT，再加载共享 Core。Runtime Adapter 负责入口格式、上下文加载以及当前运行时的模型、工具、Skill 调用和 Herdr 适配；任务分级、权限、Task Contract 和验收规则由 Core 维护。这里的 Runtime Adapter 指各入口 Prompt / Skill 与适配文档中的约定，由运行时按自身能力解释执行，并非独立的可执行程序。

2.2 Core：跨 Runtime 的唯一规则来源

每类规则只在一个权威文件中定义，Runtime 入口和其他文档通过引用使用，减少重复规则造成的不一致。

图 2A｜Claude Code 与 Pi 提供两个 Main 入口，共用 AGENT_WORKBENCH_ROOT 和 Core 规则；Runtime Adapter 负责入口适配，Core 保持任务规则的唯一来源。

2.3 Herdr 与 Pi 子 Agent：受控委派和独立执行

Main 按任务类型和风险，通过 Herdr 启动 Pi 子 Agent。常见子任务包括仓库调研、外部资料调研、L2 代码实现、Debug 诊断、独立 Review 和按需 Test。Main 负责任务目标、决策、授权、阶段门禁和验收；子 Agent 在 Task Contract 限定的范围内执行并交付证据。

Herdr 自动化分为 Layout、Pane 和 Agent 三层：Layout 管理 Workspace / Tab / Pane；Pane 控制原始终端；Agent 层启动和控制识别到的 Pi Agent，并观察 working、blocked、idle 等状态。herdr agent start 需要一个已经存在、位于 Shell Prompt 的 Pane，它本身不会创建或拆分 Pane。Main 应先创建或选择 Workspace / Tab / Shell Pane，再从命令响应中读取实际 Pane ID 启动 Pi。

典型调度顺序如下（示例假设 Main 已运行在可用的 Herdr Pane 中，并已安装 jq）：

# 1. 在 Main Pane 旁边创建 Shell Pane
split_json=$(herdr pane split --current --direction right --no-focus)
PI_PANE_ID=$(printf '%s\n' "$split_json" | jq -r '.result.pane.pane_id')

# 2. 在该 Pane 中启动 Pi Agent
herdr agent start implementer --kind pi --pane "$PI_PANE_ID"

# 3. Main 按 core/task-contract.md 组装完整 Task Contract
TASK_CONTRACT_PROMPT='<Main 生成的完整 Task Contract>'

# 4. 传入任务并等待 Agent 状态变化
herdr agent prompt implementer "$TASK_CONTRACT_PROMPT" --wait --timeout 300000

# 5. 读取 Agent 输出；文件与 Diff 仍需独立核验
herdr agent read implementer --source recent-unwrapped --lines 120

这是 Runtime 文档中的典型 CLI 示例，不是跨版本固定接口。实际使用前查看本机 Herdr Help 或 MCP Schema；Pane ID 必须从创建命令的响应中读取，不能猜测。等待超时或出现 agent_prompt_stalled 后，先读取 Agent 状态和输出，再决定是否重试；超时不代表 Prompt 一定没有发送，盲目重试可能造成重复任务。Agent 处于 blocked 时，先读取阻塞原因并处理所需输入，agent prompt 不会直接向已 blocked 的 Agent 提交新任务。

Main 收到输出后，还要检查子 Agent 写入的任务产物、当前源码和 Git Diff。Herdr 状态用于运行协调，子 Agent 自报 DONE 和终端摘要均不能代替 Main 验收。

图 2B｜Main 通过 Herdr 委派 Pi 子 Agent，任务产物回流后，Main 独立检查源码、Diff 和测试并完成验收。

2.4 Skills：可复用能力与 Runtime 解耦

skills/ 是个人 Skills 的统一维护源。当前仓库内置 ui-impl，也允许维护个人 Skill 和经审查导入的第三方 Skill。Skills CLI 可以将同一份源文件以 Symlink 方式安装到多个 Agent Runtime；具体安装位置和发现行为由目标 Runtime 决定。

工作流复用 mattpocock/skills 中的部分工程 Skills。上游 implement、grill-with-docs 和 retro 的 frontmatter 设置了 disable-model-invocation: true，表示模型不会自主选择并调用这些 Skill；用户或编排器仍可显式启动它们。在 Claude Code 中由用户输入 /skill-name；在 Pi 交互式会话或通过 Herdr agent prompt 向 Pi Agent 派发时，统一使用 /skill:<name>（Herdr 派发时将其放在 Prompt 开头，再附 Task Contract 和必要上下文）。该 Pi 触发约定适用于所有已安装到目标 Pi Agent 的 Skills，例如 /skill:implement、/skill:grill-with-docs、/skill:retro 和 /skill:ui-impl。

显式加载 parent Skill 与执行 parent 声明的嵌套依赖属于两个环节。Claude Code 中，parent 可以按上游定义通过 Skill Tool 调用依赖；Pi 中使用 /skill:<name> 只表示 parent 成功加载，不会自动将正文里的 Claude Code Skill Tool 调用转换为 Pi 的独立 Skill 调用。Pi 场景需要某项依赖能力时，由 Main 单独派发对应 /skill:<dependency> 并核验执行结果；没有单独派发时使用 Core fallback。Handoff 分别记录 parent 是否加载、嵌套依赖是否执行，以及跳过或不支持的原因。

Core 只引用逻辑 Skill 名称，由 Runtime Adapter 映射各运行时的调用语法与约束边界：

上游 implement 面向 spec / ticket 驱动的实现：传入 Issue / Ticket 引用时会尝试从 Tracker 读取详情，并在上游定义中通过 Claude Code Skill Tool 请求调用 tdd 和 code-review。在 Pi 中，如需 TDD 能力，Main 可单独派发 /skill:tdd（按需配合已安装的 codebase-design）；而上游 code-review 要求项目提供 docs/agents/issue-tracker.md 等 Tracker 配置与用户指定的 fixed point，使用 git diff <fixed-point>...HEAD（三点比较 merge-base 到 HEAD）审查已提交的分支变更，不包含 staged / unstaged 工作区修改，缺少 Tracker 时还会提示运行 /setup-matt-pocock-skills。

使用该链路时需注意三项边界：第一，本工作流的 Task Contract 不等同于 Tracker 配置，也不自动提供 fixed point、生成 Tracker 文件或运行 setup；未满足前置条件时，不调用上游 implement / code-review，直接按 Core 实现与独立 Review 流程执行。第二，未提交的工作区修改仍须按 Core Workspace Baseline 和独立 Primary Review 审查；上游 code-review 仅作为 Implementer 自检，不能替代 Core 要求的独立 Primary Review。第三，上游 implement 包含提交分支的建议，而本仓库默认不执行 Git commit / push，除非用户对当前任务明确授权。

2.5 环境与依赖：哪些组件负责运行工作流

仓库保存规则和入口，运行时依赖需要在本机单独安装与配置。依赖按必要程度分为：

建议安装 Herdr Pi Integration，以提供 Pi Session 身份、状态上报和会话恢复支持。基础 Pane / Agent 调度由 Herdr 自动化能力提供，Integration 属于增强项，不会替代 Main 建立 Pane、启动 Agent、传递 Task Contract 和读取结果的职责。详细安装与配置见仓库中的 runtimes/README.md；第三方 Skills 的安装分流见 skills/README.md。

图 3｜将依赖分为运行必需、安装同步和按需启用三类；详细安装条件与 Tracker 等前置要求见正文依赖表。

2.6 项目内任务产物

每个 L2 任务将上下文产物写入目标项目仓库：

.agents/workflow/tasks/<task-id>/

agent-workbench 中的模板位于 core/templates/；模板定义产物结构，实际任务文档和截图写入目标项目。workspace-baseline/ 仅在任务获得授权、且目标路径与任务开始前的已有修改重叠时生成，用来保存必要的任务前快照。这样工作流规则与项目任务记录分离，同时保留任务与代码仓库的对应关系。

2.7 仓库目录一览

agent-workbench/
├── README.md
├── core/
│   ├── README.md
│   ├── workflow.md
│   ├── task-classification.md
│   ├── model-routing.md
│   ├── permissions.md
│   ├── task-contract.md
│   ├── acceptance.md
│   ├── templates/
│   │   ├── overview.template.md
│   │   ├── decisions.template.md
│   │   └── handoff.template.md
│   └── references/
│       ├── code-retrieval.md
│       └── review-escalation.md
├── runtimes/
│   ├── README.md
│   ├── claude-code/
│   │   ├── README.md
│   │   └── workflow/SKILL.md
│   └── pi/
│       ├── README.md
│       └── workflow.md
├── skills/
│   ├── README.md
│   └── ui-impl/SKILL.md
└── scripts/
    └── install-runtime-links.sh

3. 角色分工与决策权属：谁负责分析、执行和批准

工作流使用逻辑角色表达职责，再由 core/model-routing.md 给出模型偏好。模型名称是目标偏好，不是固定 Provider 配置；实际 Provider、Model ID、Thinking 和能力以部署环境为准。

3.1 Main / Planner

Main 可以运行在 Claude Code 或 Pi 中，负责：

• 理解用户目标、任务类型和风险级别。
• 收集证据、解决关键歧义、制定方案并记录实质性决策。
• 通过 Herdr 派发子 Agent，明确范围、约束、Skill、References 和验收条件。
• 汇总 Research、Handoff、Test 和 Review 结果，执行 Gate。
• 为适用任务整理 Developer Review Package，并依据人工反馈继续、修正或验收。
• 维护 L2 overview.md，检查决策记录和 Implementation Walkthrough 是否完整。

Main 不直接实现 L2 业务代码。L2 实现由 Herdr → Pi Implementer 执行。

3.2 子 Agent 角色与模型偏好

Main 模型偏好：Claude Code Main 使用 Claude Opus 5.5；Pi Main 可使用 Claude Opus 5.5 或 GPT-6.1 Sol。

3.3 Decision Ownership：不同类型的决定由谁负责

core/permissions.md 明确了决策权属：

• 用户 / Product or Domain Owner 拥有原始产品意图、目标、范围和最终业务取舍的决定权；需要业务权衡的决策应在依赖它的实现开始前完成批准。
• Main 可以在用户目标、已确认决策和项目约定范围内选择执行方案，并记录实质性决策及其来源；无法从需求或项目约定确定的重要产品行为、契约或架构选择，应先 Clarify。
• 子 Agent 可以研究、比较选项并提出建议；不能擅自扩大范围，也不能把未经确认的产品行为或契约选择当成已批准决定。
• Developer / Technical Owner 通过 Developer Review 确认自己理解并接受审阅包中明确呈现的关键实现、技术取舍和维护风险。
• Product / Domain Approval 与 Developer Review 可以由同一人完成，但记录和责任不可混同。Developer Review 不能补做或代替业务批准，也不能授权审阅包之外的改动。

图 4A｜用户 / Product Owner 保留业务取舍决定权；Main 负责工程编排；子 Agent 在授权范围内执行；Developer / Technical Owner 负责理解并接受明确呈现的技术实现。

图 4B｜Main 建立任务目标和授权，Herdr 协调 Pane 与 Session，Pi 子 Agent 执行任务并回传产物，最终由 Main 独立验收。

4. 一次任务如何流转：从 /workflow 到最终验收

以下以“为账户设置页增加二步验证开关，并补齐相关测试”为例，说明一项典型 L2 实施任务。

4.1 启动与 Intake

在 Claude Code 或 Pi 中输入：

/workflow 为账户设置页增加二步验证开关，并补齐相关测试

入口加载共享 Core 后，Main 明确：

• 原始目标、预期交付物和验收条件。
• 修改范围、非目标、项目规范和依赖。
• 风险、数据或 API 契约影响。
• 当前分支、工作区状态、用户既有未提交修改和 Diff 基线。

如果判定为 L2，Main 在目标项目的 .agents/workflow/tasks/<task-id>/overview.md 建立任务总览，并记录 Workspace Baseline（当前分支、Base Commit、初始 Git 状态、已有 Modified / Untracked 路径、重叠路径处理方式与允许修改范围）。工作流默认排除任务前已修改的路径；确需修改重叠路径时，须先取得用户明确授权并建立任务前快照（详见 §5.4）。

4.2 任务分级：L0 / L1 / L2

任务级别按影响范围和风险判定，任务类型按实际交付目标判定，两者分别处理。

这里的 L0 / L1 是工作流启动后的轻量处理路径，并不意味着建议为简单请求专门调用 /workflow；文案、注释、纯文字配置和低风险单文件修改直接在当前 Agent 对话中完成即可。文件数量和变更行数只是判断线索，单文件安全修复或接口/数据契约变更因具有实质风险，仍属于 L2。

变更行数按 Git Diff 中新增行数与删除行数之和计算，实施过程中以实际 Diff 判断是否需要升级为 L2。L1 实施中如果实际触及第二个文件、总变更超过 50 行，或出现跨模块行为、接口/数据契约及实质风险，Main 会暂停直接修改，保存当前 Diff 和工作区状态，再升级为 L2 并委派 Implementer。

任务类型包括 Research、Plan / Architecture、Implement、Visual Implementation、Review、Test、Debug、Documentation、Issue / Ticket 和 Mixed。纯调研、规划、Review 或 Test 任务只执行完成目标所需的最小阶段，不强行走完完整实现流水线；Debug 任务则先走诊断分支，仅在需要修复时按修复本身的风险重新分级（见 §4.4）。

图 5A｜先判断任务是否值得启动完整工作流，再按影响范围和风险选择 L0 / L1 或 L2；多文件修改按 Core 规则进入 L2。

4.3 Research、Clarify、Decision Trace 与 Plan

进入 L2 主流程后，实施前的准备阶段按需推进：

• Research：Main 按需委派 Repo Researcher 和 Web Researcher。调研结果须区分事实、推断和待确认事项，并提供代码路径、符号、行号或外部来源。
• Clarify：当歧义会实质影响行为、范围、兼容性、数据或验收时，Main 先通过已有会话、源码和项目文档排查可自行确认的问题；仍需业务或架构权衡时再向用户 Clarify。
• Decision Trace：出现实质性产品、交互、架构、接口、数据、安全、兼容性或性能决策时，必须创建 decisions.md（完整字段见 §5.3）。其中 Origin 区分 USER_APPROVED、PROJECT_CONVENTION 与 AGENT_PROPOSAL；Status 使用 PROPOSED、CONFIRMED、REJECTED 或 DEFERRED；无实质性决策时在 overview.md 标注 No material decisions。实施期间发现新的实质性选择时，须先更新记录（需用户权衡的先完成确认），再继续依赖该决定的工作。
• Plan：所有 L2 代码变更在实施前都必须有可执行方案。达到 task-classification.md 中任一条件时生成 plan.md；其他 L2 任务将方案写入 Task Contract 和委派消息。

图 5B｜L2 代码实施主流程：实施前完成需求澄清、实质性决策记录与必要业务批准；随后进入代码实施、独立验证与自动化门禁；Gate 通过后按风险触发 Developer Review，最后完成 Acceptance 与知识沉淀。

4.4 Debug、Implement、Handoff、Test 和 AI Review

Debug 任务先复现问题、诊断根因并收集证据；仅诊断时以 debug-report.md 验收结束；需要代码修复时按修复本身的风险重新分级，L2 修复进入完整的 Implement、Handoff、Test、Review 和 Gate。

图 5C｜Debug 先完成复现和诊断报告；仅诊断即可结束，需要修复时再按修复风险进入 L0 / L1 或 L2 流程。

L2 代码实现由 Main 通过 Herdr 派发 Pi Implementer，默认按 Core Task Contract 在授权范围内完成代码修改、基础检查与 handoff.md（视觉任务须加载 ui-impl；若满足 §2.4 的 Tracker 与 fixed point 前置条件，也可通过 /skill:implement <Issue / Spec URL> 显式加载上游编排，但其自检不能替代独立 Primary Review）。

所有 L2 实现任务的 handoff.md 必须包含 Implementation Walkthrough，说明：

• 主要调用链和数据流；
• 新增或修改的关键抽象、状态和领域规则；
• 重要技术取舍及其决策记录；
• 后续扩展入口；
• 常见问题的排查入口。

Main 先读取 Handoff，再检查实际 Diff、关键源码和检查结果。Handoff 完整后，独立 Test 和 Primary Review 可以并行：所有 L2 代码变更都必须执行 Primary Review；Tester、Secondary Review 和 Expert 按风险触发。

4.5 Gate、Developer Review 与 Acceptance

必需测试、Primary Review 和已触发的补充 Review 完成后进入自动化 Gate。存在未解决 P0/P1 时执行定向修复与复审（最多两轮），第二轮后仍未解决则标记 BLOCKED。

业务批准与技术审阅处于不同节点：若 decisions.md 中的 Product / Domain Approval 仍为 PENDING，Main 必须在依赖该决定的实现开始前暂停并记为 NEEDS USER DECISION；Developer Review 则在自动化 Gate 通过后按风险触发。Main 在 overview.md 中标注 REQUIRED、RECOMMENDED 或 NOT REQUIRED 及理由；REQUIRED 任务在获得开发者明确批准前保持 NEEDS DEVELOPER REVIEW，不从测试通过、AI Review PASS、子 Agent DONE 或用户沉默推断批准（触发条件与审阅包详见 §6.4）。

4.6 Knowledge Update 与 Retro

完成 Acceptance 后，Main 在任务授权范围内评估值得长期保留的知识：

• ADR / Architecture Docs：稳定的架构边界、公共契约和领域规则；
• 项目文档或 AGENTS.md：经验证的模块入口、调用链和排障方法；
• 个人 Skill：可跨项目复用的 Agent 执行方法。

未获授权或暂不适合沉淀的候选项记入 overview.md / retro.md 并说明原因；一次性实现细节和短期调试过程保留在任务目录，不机械复制到长期知识库。出现重复失败、模型路由错误、成本异常、并行冲突或交付缺口时，再按需执行 Retro。

5. 上下文如何传递：Task Contract 与任务产物

core/task-contract.md 定义委派协议，子 Agent 不依赖继承 Main 的完整会话历史，而是接收本次任务实际需要的目标、范围、证据、权限和验收条件。

5.1 Task Contract 传递什么

针对 Visual Implementation 任务，Task Contract 还会额外包含 Reference、Target、Viewport、States 和 Assets 字段。

5.2 任务产物各自解决什么问题

默认任务目录：

.agents/workflow/tasks/<task-id>/
├── overview.md
├── workspace-baseline/       # 仅在授权重叠路径时创建
├── research.md
├── debug-report.md           # 仅诊断任务
├── decisions.md
├── plan.md
├── handoff.md
├── review.md
├── review-secondary.md
├── review-escalation.md
├── test-report.md
├── visual-report.md
├── screenshots/
└── retro.md

以上是可能出现的产物集合。具体任务只创建被触发的文件：所有 L2 任务必须有 overview.md；存在经用户授权的重叠脏路径时才创建 workspace-baseline/；有实质性决策时创建 decisions.md；L2 实施任务的 handoff.md 必须包含 Walkthrough；其他报告按相应阶段创建。

5.3 三个关键模板

overview.template.md：任务导航和审阅摘要。 它不复制各份报告的全文，而是提供相对路径链接与全局状态索引（完整字段构成见 §7.2）；对未触发的阶段明确标注 N/A，不生成空白报告。

decisions.template.md：决策登记。 每项实质性决策记录 Type、Origin、Decision Owner、Status、Product / Domain Approval、Approved By、Approval Evidence、Affected Areas，以及 Context、Problem、Options、Decision、Rationale、Trade-offs、Evidence 和 Follow-up。待确认和延后事项统一汇总到 Deferred / Unresolved Decisions。

handoff.template.md：实现理解。 包含执行状态、需求与决策映射表、§4.4 所述的 Implementation Walkthrough、契约与兼容性说明、验证结果及剩余限制。当 Task Contract 指定了 Skill 时，还须填写 Skill Loading & Execution 表，记录每个 Skill 的调用策略、目标 Runtime 安装状态、parent 是否加载、嵌套依赖执行结果（如 UNSUPPORTED / SKIPPED）以及是否回退到 Core。它用于解释本次实现如何工作，不替代代码 Diff。

5.4 Workspace Baseline：先区分已有修改，再审查本次变更

Base Commit 只表示任务开始时的 HEAD。git diff <base> 仍然包含任务开始前已经存在的工作区修改，不能单独证明这些变更属于当前任务。Main 默认将已有脏文件从本次 Allowed Paths 排除；任务前已有的 Untracked 文件也不能被当作本次新增文件。

确实需要修改与已有脏文件重叠的路径时，Main 必须先说明重叠路径和风险，取得用户明确授权，再在任何子 Agent 写入前为相关文件建立任务前快照（Overlap Handling: USER_AUTHORIZED_WITH_SNAPSHOT），放入 workspace-baseline/。快照只包含必要文件，遵循与源文件相同的访问控制，不复制无关凭据或私密数据，也不混入产品构建、发布包或实现提交；无法安全建立可靠快照时，将该路径标记为 BLOCKED 并暂停写入。审查阶段若无法可靠区分任务变更与既有变更，相关 Review 标记为 INCOMPLETE，Main 不得放行 PASS。任务结束时，Main 在 overview.md 标注快照位置和处理建议，由用户或项目约定决定是否清理。

5.5 上下文与结果如何回流

Main 在委派前确认子 Agent 可以访问 Contract 指定的文件：其中 References 路径相对于 AGENT_WORKBENCH_ROOT 解析，而 Scope 与任务产物路径（.agents/workflow/tasks/<task-id>/）相对于目标项目根目录。执行所需 Skill 必须由实际子 Agent 加载；Core 中的逻辑 Skill 名称由 Runtime Adapter 映射为 Claude Code /skill-name 或 Pi /skill:<name>。无法访问某份 Reference 时，Main 将必要规则摘要或片段写入 Context。

子 Agent 写入任务目录并返回状态、产物路径、实际模型信息和未完成事项。Main 既读取报告，也独立检查 Workspace Baseline、实际 Diff、源码和测试结果。任务目录只隔离文档、快照和截图，不会自动隔离共享代码工作区。

图 6A｜Main 将目标、范围、权限和验收标准组装为 Task Contract，经 Herdr 交给 Pi 子 Agent；任务报告和证据回流 Main 进行独立核验。

图 6B｜干净路径以 Base Commit 为比较基准；已有修改默认排除，授权重叠路径先快照再比较；无法安全建立快照时路径标记 BLOCKED，审查时无法可靠区分变更归属则标记 INCOMPLETE。

6. 结果汇总与质量门禁：AI Review、Developer Review 和修复闭环

多 Agent 输出可能互相补充，也可能出现重复发现或观点冲突。agent-workbench 将自动化代码审查与面向开发者的人工审阅分开定义：前者检查实现质量和需求一致性；后者确认关键实现和决策是否符合原始意图、开发者是否理解并接受重要取舍。

6.1 Test 与 Primary Review

• Implementer 先运行与修改范围直接相关的基础检查，记录在 handoff.md。
• 高风险、跨模块、关键契约或独立验证能增加覆盖时，Main 委派 Tester；简单变更可复用真实执行过的基础检查。
• 所有 L2 代码变更必须执行独立 Primary Review，完整覆盖约定 Diff；Reviewer 的实际模型家族必须与 Implementer 不同。
• Review 输入包括完整 Workspace Baseline、依据路径状态确定的任务专属 Diff、原始需求和验收标准、research.md / decisions.md（如有）、plan.md（如有）、handoff.md、项目规范和必要测试结果。干净且无重叠的路径结合 Base Commit 检查 Diff；授权重叠路径比较 workspace-baseline/ 快照与最终文件并单独说明本次变更；EXCLUDED 路径不作为本次实现变更审查；无法安全建立快照的 BLOCKED 路径不得继续实现或获得 Review PASS。若 Reviewer 未覆盖完整约定 Diff，或无法可靠区分任务变更与既有修改，相关 Review 必须标记 INCOMPLETE，Main 不得放行 PASS。

Reviewer 除检查代码缺陷外，还要核对实现与原始需求、已确认决策和项目约定是否一致，特别是实现过程中是否出现未记录的产品行为、交互、架构、API 或数据契约选择。若 Implementer 在执行中升级到 Claude Sonnet 5.5 / Opus 5.5，Main 必须重新核对 Reviewer 模型家族，按 core/model-routing.md 选择与 Implementer 不同家族的模型。测试场景也应覆盖 decisions.md 中已确认且可验证的行为或契约决策。

Finding 严重级别：

• P0：发布阻断、核心功能失效、严重数据、安全、权限或契约问题。
• P1：明确缺陷、重要行为错误，或缺失测试会掩盖具体且重要的风险。
• P2：非阻断改进、边界建议或偏好性意见，不触发自动修复循环。

Finding 使用 ID | Severity | File:Line | Issue | Evidence | Suggested Fix；涉及意图或决策偏差时补充 Requirement / Decision Ref。

6.2 Secondary Review 与定向升级

普通、范围明确且风险可控的 L2 任务只执行 Primary Review。涉及安全/权限、迁移/一致性、核心契约、复杂跨模块 Diff 或具体高影响测试缺口时，才触发 GLM-5.3 Flash Secondary Review。

Secondary Reviewer 使用独立 Pi Session，基于相同的原始需求、验收标准、research.md / decisions.md、Diff、Plan / Handoff 和测试证据独立盲审，第一轮完成前不读取 Primary Reviewer 的 Findings。Main 随后合并重复项、保留实质分歧，并依据源码、Diff、需求、决策和测试证据裁决。

Reviewer Escalation 仅在 P0/P1 实质争议或高影响问题仍无法形成证据结论时定向介入。默认模型偏好为 Claude Sonnet 5.5；如果 Implementer 已升级到 Claude 模型家族，则按 core/model-routing.md 优先选择尚未参与当前争议的 GLM-5.3 Flash，不可用或已参与时改选 GPT-6 Luna。若 Luna 与 GLM 已分别作为 Primary / Secondary 参与分歧，且没有其他可用的不同模型家族 Reviewer，Main 不重复委派已参与的 Reviewer，也不启动同家族审查，而是根据原始需求、源码、Diff、测试和双方证据直接裁决并记录理由；仍无法形成有证据的结论时，未解决的 P0/P1 保持 BLOCKED。Escalation 不重新扫描整个仓库，也不替代 Main 最终决策。

6.3 Gate 与修复

必需测试、Primary Review 和所有已触发的补充审查完成后进入 Gate。存在 P0/P1 时，由原 Implementer 定向修复，运行针对性回归，并由 Primary Reviewer 复审修复 Diff。复审结果返回 Main Gate 重新核验，最多修复与复审两轮；第二轮后仍存在 P0/P1，标记 BLOCKED。

Main 不以模型数量或多数票代替证据，而是核对真实源码、当前 Diff、需求、Decision ID、契约和测试结果。INCOMPLETE Review 不放行。

6.4 Developer Review 与 Product / Domain Approval：分开确认技术实现和业务意图

两类确认承担不同责任：

同一人可以承担两种责任，但批准记录必须区分。Developer Review 位于自动化验证、AI Review 和 Main Gate 之后、最终 Acceptance 之前；它不替代 AI Review 或业务批准，也不允许绕过 P0/P1 门禁。

Main 必须为每个 L2 任务在 overview.md 中记录 REQUIRED、RECOMMENDED 或 NOT REQUIRED 及理由。以下情形必须标记为 REQUIRED：

• 用户可见的产品规则、业务行为或交互设计发生变化；
• 公共 API、事件、数据结构、数据库 Schema 或跨模块契约发生变化；
• 架构边界、核心抽象、关键依赖或跨模块设计发生实质调整；
• 涉及认证授权、安全、敏感数据、事务、一致性、并发或权限边界；
• 涉及数据迁移、破坏性变更、兼容性取舍或难以回滚的操作；
• Agent 实质性产品/设计决策尚未确认，或原始意图存在会影响结果的重要不确定性。

用户明确要求审阅时一律为 REQUIRED。普通、范围受控、遵循既有项目约定且没有实质性行为/契约决策的 L2 修改，可以标记 RECOMMENDED 或 NOT REQUIRED，但必须在 overview.md 记录依据。

Developer Review Package

Main 至少提供：

1. overview.md：目标、范围、状态和产物导航；
2. decisions.md（如有）：选项、决策来源、理由、取舍和确认状态；
3. handoff.md（实施任务）：Implementation Walkthrough；
4. 关键 Diff：重要文件、符号、变更位置和基准；
5. review.md 及补充 Review（适用时）；
6. test-report.md（执行独立测试时）；
7. 未解决假设、风险、技术债和后续建议。

开发者从 overview.md 进入其他产物，再按需查看源码和 Diff；流程不要求逐行阅读所有实现才能掌握关键变化。

批准与反馈

REQUIRED 任务在开发者明确确认前，Verdict 为 NEEDS DEVELOPER REVIEW。Main 不从测试通过、AI Reviewer PASS、子 Agent DONE 或用户沉默推断批准。

开发者可以批准、要求修改或要求澄清。批准记录在 overview.md，包括确认来源、审阅基准 Commit / 变更范围和结果。批准后若代码、决策或验收范围发生实质变化，必须更新审阅包并重新请求受影响部分的确认。要求澄清时回到 Clarify 更新决策与方案；要求修改时重新执行受影响的实现、Test、Review 和 Gate，完成后更新审阅包并重新请求相应范围的确认。

开发者批准表示接受已呈现的实现和技术取舍，不改变测试、Review、安全和权限门禁。若 decisions.md 中的 Product / Domain Approval 仍为 PENDING，Verdict 使用 NEEDS USER DECISION，而不是 NEEDS DEVELOPER REVIEW；任何未解决 P0/P1 仍然阻止 PASS。

6.5 Acceptance 与 Knowledge Update

最终 PASS 必须同时满足：全部必需验收条件达成、必需测试真实执行、Review 完整通过、无未解决 P0/P1、必要用户业务决策已完成，且所有 REQUIRED Developer Review 已明确批准。

完成 Acceptance 后，Main 按 §4.6 的规则与任务授权范围评估 Knowledge Update（如沉淀 ADR、更新项目文档 / AGENTS.md 或提炼个人 Skill），将未获授权或暂不适合长期保存的候选项留在 overview.md / retro.md 中。

图 7A｜Implementer 完成基础检查与 Handoff 后，由 Primary Reviewer 独立检查全部 L2 代码变更；Secondary Review / Tester 按风险触发，最终由 Main Gate 根据证据裁决。

图 7B｜Product / Domain Approval 在依赖业务决定的实现开始前完成；Developer Review 在自动化 Gate 通过后按风险触发；所有必需条件满足后进入 Acceptance。

7. 开发者从哪里理解一次任务：以 overview.md 为审阅入口

overview.md 是所有 L2 任务的统一审阅入口，提供全局导航与摘要，避免开发者在多份任务产物之间自行拼接上下文。

7.1 推荐阅读顺序

7.2 overview.md 包含什么

仓库的 core/templates/overview.template.md 包含以下主要模块：

• Status：Task ID、类型/级别、Main Runtime / Model、当前阶段、Verdict、Developer Review 要求、状态与判定理由；
• Workspace Baseline：分支、Base Commit、初始状态、既有脏路径/未跟踪路径、重叠处理策略、快照路径与允许修改范围；
• Intent：原始目标、范围/非目标、验收标准和用户约束；
• Participants：各角色、Runtime / Model、职责和结果；
• Artifact Index：Baseline 快照、Research、Debug、Decisions、Plan、Handoff、Review、Test、Visual 和 Retro 的路径与状态；
• Key Changes / Decision Index：关键变更映射表和决策索引；
• Implementation Understanding：主调用/数据流、核心抽象、重要取舍、扩展和排障入口；
• Verification Summary：测试、AI Review、P0/P1、视觉验证和已知覆盖缺口；
• Product / Domain Approval & Developer Review Package：业务决策批准状态，以及面向开发者的关键文件/Diff 位置、待关注决策、审阅问题、审阅范围基线和批准证据；
• Open Risks & Next Steps / Knowledge Update Candidates：未解决假设、延后决策、技术债、后续建议和长期知识沉淀候选项。

7.3 这如何帮助开发者审阅关键改动

建议将审阅分成三层：

1. 先理解意图：从 overview.md 和 decisions.md 了解为什么要改、有哪些已确认选择，以及哪些假设仍待确认。
2. 再理解实现：通过 handoff.md 的 Implementation Walkthrough 找到关键调用链、状态和数据契约，再按链接检查真实源码与 Diff。
3. 最后核验质量：查看 Review Finding、Test 结果和视觉证据，确认自动化验证覆盖了哪些内容、仍有哪些盲区。

对于 REQUIRED 的 Developer Review，Main 会把这组文件和关键 Diff 整理为 Developer Review Package。开发者可以从摘要一路追查到源码、测试和决策证据，对存疑的实现要求修改或澄清。

图 8｜将 §7.1 的阅读顺序收敛为五个步骤：从 overview.md（01）出发，依次查看 decisions.md（02）与 handoff.md Walkthrough（03），再核对 Diff、Review、Test 与视觉证据（04，对应 §7.1 第 4–7 项），最后在明确呈现的审阅范围内完成确认或反馈（05）。

8. 专项流程：ui-impl 如何完成视觉实现

skills/ui-impl/SKILL.md 将视觉还原定义为专项实施能力，不新增 Agent 角色。通用实现流程、权限和交付要求由 Core Task Contract 定义；ui-impl 负责视觉分析、还原方法和浏览器验证步骤（如需结合上游 implement，同样受 §2.4 所述前置条件约束）。

8.1 输入和前置条件

Visual Task Contract 需要提供 Reference、Target、Viewport、States、Assets 和项目约束。执行环境需要能够访问目标仓库和页面、视觉参考、可理解图像的模型能力、agent-browser 集成，以及让截图作为图像内容进入模型上下文的途径。

Skill 支持通过 CLI、MCP 或 Runtime Native Tool 使用 agent-browser；具体工具名称和参数以当前环境为准。浏览器和图片能力不满足时，仍可执行有证据支持的代码工作，但视觉验证必须标记 NOT VERIFIED。

8.2 实现与视觉迭代

Pi Implementer 先检查项目路由、组件、Token、字体、图标和素材，优先复用现有约定；随后先实现宏观布局和几何，再逐步处理排版、颜色、边框、阴影和细节。

通过真实浏览器打开目标页面，匹配参考图的 Viewport、Route、状态和滚动位置，等待字体、图片和异步内容完成后截图。模型必须实际读取截图，并与参考图比较。按最大影响优先修正差异，再在相同条件下截图复核。Skill 将“初始实现 + 三轮重点修正”作为计划基线，而非硬性迭代上限。

8.3 视觉产物

.agents/workflow/tasks/<task-id>/
├── visual-report.md
└── screenshots/
    ├── iteration-1.png
    ├── iteration-2.png
    └── final.png

visual-report.md 记录参考、目标路由、Viewport、页面状态、实现文件、浏览器操作、截图路径、比较结果、剩余差异、限制和验证状态。Handoff 引用该报告和最终截图。视觉、功能和代码验证分别报告。

图 9｜参考图和任务约束进入 ui-impl，Implementer 通过 agent-browser 渲染页面，截图进入视觉比较，差异反馈到下一轮实现，最终报告和截图返回 Main。

9. 如何安装与使用：两个入口共享同一份 Core

安装前建议先阅读 仓库 README 和 Runtime 使用说明。

9.1 准备运行环境并设置仓库路径

基本运行环境包括：Herdr、Pi Coding Agent、可用的模型 Provider / Model 访问权限，以及 Claude Code 或 Pi 中任选其一作为 Main Runtime。安装或同步 Skills 时还需要 Node.js、pnpm 和 Skills CLI；视觉任务按需准备 agent-browser 与图片理解能力。依赖和用途见 §2.5。

将仓库放在稳定位置，例如 ~/Workspace/agent-workbench，在 Shell Profile 中设置唯一环境变量：

export AGENT_WORKBENCH_ROOT="$HOME/Workspace/agent-workbench"

两个 Main Runtime 和 Herdr 启动的 Pi 子 Agent 都必须能读取该变量。通过桌面应用启动 Runtime 或 Herdr 时，需要确认对应进程和子进程继承了变量；仅在交互式 Shell 中设置，不保证 GUI 进程自动读取。变量缺失或路径无效时，入口暂停并报告配置问题，不猜测仓库位置。

9.2 安装 Claude Code 入口

通过 Skills CLI 将 Claude Code Skill 全局安装，交互时选择 Symlink：

pnpx skills add "$AGENT_WORKBENCH_ROOT/runtimes/claude-code" \
  --skill workflow \
  --agent claude-code \
  --global

随后使用：

/workflow <任务目标>

9.3 安装 Pi 入口

在仓库根目录执行：

cd "$AGENT_WORKBENCH_ROOT"
./scripts/install-runtime-links.sh

脚本将 runtimes/pi/workflow.md Symlink 到 Pi Prompt Template 目录。默认位置为 ~/.pi/agent/prompts/，也可通过 PI_CODING_AGENT_DIR 调整。活动 Pi Session 执行 /reload 后使用 /workflow <任务目标>。

图 10A｜Main Runtime 加载 Core 后，通过 Herdr 准备 Shell Pane、启动 Pi Agent、传入 Task Contract、读取状态和输出，最后独立核验任务结果。

9.4 安装共享 Skills

例如将 ui-impl 安装到 Claude Code 和 Pi：

pnpx skills add "$AGENT_WORKBENCH_ROOT/skills" \
  --skill ui-impl \
  --agent claude-code \
  --agent pi \
  --global

安装时选择 Symlink。skills/ 是个人 Skills 的统一维护源，也可保存第三方 Skills；导入第三方 Skill 时需记录来源仓库、原始路径、Commit、许可证、同步时间和本地修改，安装或升级上游前先检查 frontmatter、依赖、脚本与副作用并比较 Diff。

第三方工程 Skills 安装分流

mattpocock/skills 按 Runtime 角色与前置条件分流安装（调用语法、parent 与嵌套依赖边界见 §2.4，完整说明见仓库 skills/README.md）：

1. Pi 子 Agent 默认安装 TDD 与设计辅助（不依赖 Issue Tracker，tdd 需配套 codebase-design）：

pnpx skills add https://github.com/mattpocock/skills \
  --skill tdd --skill codebase-design \
  --agent pi --global

2. 按需条件安装上游 implement 与 code-review 到 Pi：implement 和第三方 code-review 均不作为默认安装项。第三方 code-review 不安装到 Claude Code，以保留 Claude Code bundled /code-review。只有满足 Spec / Ticket、Tracker、fixed point 前置条件且明确选择试用时，才将两者按需安装到 Pi：

pnpx skills add https://github.com/mattpocock/skills \
  --skill implement --skill code-review \
  --agent pi --global

触发时由 Main 在 herdr agent prompt 开头发送 /skill:implement <Issue / Spec URL>；其内部 tdd / code-review 仍需按 §2.4 单独派发并核验，未满足 Tracker / fixed point 前置条件时回退到 Core Task Contract 实现与独立 Review。

3. Claude Code Main 安装需求澄清与复盘 Skills（grill-with-docs 与 retro 由用户手动输入 /skill-name 触发，其依赖随 parent 一并安装）：

pnpx skills add https://github.com/mattpocock/skills \
  --skill grill-with-docs --skill grilling --skill domain-modeling \
  --skill retro --skill writing-for-agents \
  --agent claude-code --global

4. Pi 按需安装澄清 / 复盘 parent 及其独立依赖：Pi Main 默认使用 Core Clarify / Retro；如确需在 Pi 中显式加载 grill-with-docs 或 retro parent，可按需安装：

pnpx skills add https://github.com/mattpocock/skills \
  --skill grill-with-docs --skill retro \
  --agent pi --global

由于 Pi 不会自动执行 parent 正文中的 Claude Code Skill Tool 嵌套调用，如需使用其子依赖能力，需单独安装并由 Main 通过 Herdr 发送 /skill:grilling、/skill:domain-modeling 或 /skill:writing-for-agents，并在 Handoff 中核对结果（未安装或未派发时使用 Core Clarify / Retro）：

pnpx skills add https://github.com/mattpocock/skills \
  --skill grilling --skill domain-modeling --skill writing-for-agents \
  --agent pi --global

图 10B｜Skills CLI 以 Symlink 将统一源目录安装到目标 Runtime；Claude Code 与 Pi 使用不同的显式调用语法，嵌套依赖也按各自运行时能力处理。

9.5 CodeGraph 和其他按需依赖

CodeGraph 是可选的跨文件结构检索增强，仓库引用 @colbymchenry/codegraph。它可帮助定位符号关系、调用链和变更影响；工具不可用或索引状态不确定时，按 core/references/code-retrieval.md 回退到 rg、fd 和 Read，重要结论仍需核对当前源码、Diff 和测试证据。安装与工具参数以项目文档和当前 Runtime Schema 为准。

agent-browser 与图片理解能力只在视觉实现任务中需要；jq 仅用于解析 §2.3 展示的 Herdr CLI JSON 示例。克隆仓库不会自动安装 Herdr、Pi、模型 Provider、第三方 Skills、CodeGraph 或浏览器工具，也不会提供相关凭据。

10. 适用场景、收益与使用注意事项

这套工作流面向需要多 Agent 协作、过程可追溯和独立质量验证的复杂开发任务，并非所有日常请求的默认入口。

10.1 什么时候值得启动 /workflow

10.2 设计上可以获得的收益

以下是从仓库规则推导出的预期收益，不代表已经通过量化实验验证：

1. 主控方式灵活：Claude Code 和 Pi 复用同一份 Core，主控 Runtime 与模型可以独立选择。
2. 按风险控制调度成本：简单任务由 Main 直接处理；只有达到 L2 条件时才启用完整委派和独立 Review。纯 Research / Plan / Test 等任务也只执行必要阶段。
3. 执行和验证分离：L2 实现由 Implementer 承担，Primary Review 独立审查，Tester 按风险补充验证。
4. 上下文可追踪：Task Contract 限定子 Agent 接收的目标、范围、约束、Skills、References 和验收标准。
5. 开发者有统一审阅入口：overview.md 串联决策、实现、Review、Test 和视觉证据；Walkthrough 帮助理解核心实现。
6. 意图与决策可追溯：decisions.md 记录重要选择的来源、负责人、理由、取舍和状态，Review 检查实现期间新增的实质性假设。
7. 长期知识有筛选地沉淀：Knowledge Update 评估 ADR、项目文档、AGENTS.md 和 Skill 候选项，避免机械复制所有任务报告。

10.3 使用中的注意事项

1. 按运行时核验 Skill 与模型配置：Main 已加载的 Skill 不会自动继承给子 Agent；Pi 显式加载 parent Skill 时不会自动执行 Claude Code Skill Tool 嵌套依赖（见 §2.4）；模型表仅为偏好，实际 Provider、Model ID、Thinking 和 Herdr Schema 均以运行环境为准。
2. 共享工作区须隔离变更归属：任务目录不隔离代码修改；默认排除既有脏文件与未跟踪文件，修改重叠路径须按 §5.4 取得授权、建立 workspace-baseline/ 快照并对比审查（无法安全建立快照时路径标记 BLOCKED；Review 未覆盖完整约定 Diff 或无法可靠区分变更归属时标记 INCOMPLETE）；并行实施仅限文件范围无交集的任务，Git / 分支 / worktree 操作均需明确授权。
3. 可选工具按需独立配置：CodeGraph 不可用时回退到 rg、fd 和 Read；ui-impl 依赖可用的 agent-browser、目标页面和模型读图能力，不可用时视觉状态标为 NOT VERIFIED。

10.4 当前实现边界与待确认事项

11. 总结：让 Agent 交付与开发者理解同步发生

agent-workbench 把规则、执行、验证和理解放进同一套协作链路：Runtime 入口与共享 Core 统一任务规则，Herdr → Pi 子 Agent 隔离角色执行，Task Contract 约束上下文与权限，Test / AI Review / Gate 把关实现质量，最后由 overview.md、decisions.md、handoff.md 和 Developer Review 承接任务意图、实现说明与人工确认。

围绕这套链路，开发者在审阅任务时可以直接回答四个问题：为什么要改、做了哪些重要决定、代码现在如何工作、哪些验证和人工确认已经完成。 这些机制有助于减缓 Cognitive Debt、Comprehension Debt 和 Intent Debt 的累积，但实际效果仍取决于产物质量、决策记录是否如实反映取舍、开发者是否参与重要审阅，以及长期知识是否持续维护。

附录：关键文件索引

以下链接指向公开仓库 main 分支中的对应文件，具体规则以仓库当前版本为准。