搭建个性化的 Agent Team 与 Harness

为什么？

用 Vibe Coding 推进复杂项目时，单 Agent 很快就会遇到能力瓶颈：首先是上下文窗口会被低价值信息塞满，导致任务被迫中断。其次是不同角色，包括搜索、规划、编码混在一个流程里，效率低且容易出错。最后是安全问题：缺乏全局规划容易返工，没有权限隔离还可能引发危险操作。

Agent Team 把角色拆开——规划归规划，执行归执行，读与写分离——前两个问题就缓解了大半。Harness 在更上一层做管控：分配权限、匹配模型、管理上下文、约束行为。然而，市面上的通用方案很难直接套用，每个项目的技术栈、开发约定、任务类型、研发流程各不相同，一刀切的方案很难匹配需求。

好在个性化定制一套并不复杂。打开支持多 Agent 的 IDE 或 CLI（如 Claude Code 或 OpenCode），依次完成三件事：设计架构与角色、管理权限、模型与上下文、增加 Plan 工作流。此外还有更快的方式：直接导入一套现成的 Team + Harness 框架，在其基础上按自己项目的需求裁剪调整。

第一步：设计架构与角色

从简单开始

不必一开始就把多角色团队搭建完整。可以先从一个 Agent 起步，下文称为 Builder，它大致相当于大多数 AI Coding 工具里的默认 Build Agent。然后随着任务复杂度上升，按需逐步拆分角色（Role）。每个角色在实现层面就是一个 Sub-agent，接收 Builder 委派的专项任务：

• Builder 负责所有工作；当发现上下文不足或效率下降时，考虑拆分职责。
• 增加只读角色 Explorer / Researcher：负责搜索与信息收集，把检索工作从主 Agent 卸载出去。
• 增加 Coder：专注代码实现与修改，提高编码质量与连贯性。
• 增加 Planner：在多文件或跨步骤的复杂任务中负责规划与任务分解。
• 按需再扩展 Reviewer、General 等角色，用于审查、通用协助或权限隔离。

“The best agent architecture is the one you don’t need to build. Start simple. Add complexity only when metrics prove it helps.” ——Reliable Data Engineering

核心设计原则

• 规划与执行分离：规划（决定做什么、如何拆分任务）和执行（实际实现与修改代码）是两种不同的认知活动，应由不同角色承担，避免频繁上下文切换和误操作。
• 读与写分离：搜索/读取信息与写入代码的风险和成本截然不同。读取出错最多是浪费时间，写入出错则可能损坏项目。因此应把检索类工作交给只读角色，把修改类工作交由有权限和审查流程的写入角色。
• 内部与外部分离：内部的项目代码库搜索，与外部互联网检索需要不同的工具与策略。代码库搜索依赖对项目结构的理解（如 Glob/Grep/Read），而互联网检索更侧重关键词、来源判断和信息整合。把两类检索混在同一角色里，会导致工具臃肿或策略互相干扰，应分别设计并独立治理。

Builder 的路由决策

Builder 是整个团队的决策者，应使用综合能力最强的通用模型（例如 Claude Opus），但它几乎不直接写代码，核心职责是做路由决策，把每项工作委派到最合适的角色上。

下面是一个常见的路由表示例：

人类要做的是把每个 Agent 的职责描述清楚，交给 Builder 背后的模型判断该派谁执行。使用过程中，根据实际效果调整路由规则与阈值。积累到一定程度后，还可以引入量化指标，如委派成功率、回退次数、任务完成时长，来推动分工持续迭代。

额外的行为准则

可以先在 Builder Prompt 中加入以下准则，具体数字可以交由模型决策，再逐步完善：

• Prefer Delegation：遇到不确定时，优先委派，避免 Builder 退化成全能 Agent，让上下文被细节淹没。
• 3-Failure-Stop：同一子任务连续失败 3 次，停下来问用户，不要无限重试。
• Plan Before Action：涉及 5 个以上文件或跨多步骤的任务，先交给 Planner 制定计划，不要试图一口气做完。
• Confirm Before Declaring Done：在宣布完成前，确认所有部分都已处理、代码已 review、测试已通过。

角色一览

角色（Role）在实现层面就是一个 Sub-agent，用于接收 Builder 委派的任务。角色数量没有固定答案；当某类任务高频出现，且对能力或权限有独立要求时，就值得单独拆出一个角色：

Coder（编码执行）：选用编程能力强、成本可接受的模型，负责执行已分析清楚的任务。不能调用 Task（禁止递归委派），不能使用 Skill。硬约束包括：不能通过删除已有测试来"通过测试"，不能留 TODO 或空函数体作为最终交付，必须运行测试并汇报具体结果。

Explorer（内部分析）：面向代码库的只读搜索。工具集：Glob / Grep / Read。输出必须包含 Not found 部分——搜索过但未命中的内容也要明确列出。

Researcher（外部调研）：面向互联网的只读信息搜集。工具集：Web search / URL 读取 / GitHub 浏览。所有 URL 和引用必须出现在最终消息中。搜索语言会影响结果质量，建议优先使用英文，英文技术资料通常更全面可靠。同时应多方查证，避免幻觉和信息污染。

Reviewer（审查质检）：选用带 thinking 的代码专用模型。审查优先级为 Completeness > Correctness > Quality。输出必须是 PASS / WARN / FAIL 三选一。也可用于审查 Plan。

只读角色的共同设计：Explorer、Researcher、Reviewer 均禁止 edit 和 bash 权限，目的是隔离副作用——避免只读操作误修改文件。

General（通用角色）：允许的独立运行步数最多，拥有全部工具和 Sub-agent 调度能力。用于可拆分但不易归类的任务，以及跨领域的复杂任务。

Compaction（上下文压缩）：选用长上下文模型，并开启 thinking 来判断哪些消息需要保留。

第二步：管理权限、模型、上下文

权限：最小权限

每个角色只保留完成其任务所需的最小权限集：

不少 AI Agent 存在“尽可能多做”的倾向。如果给它 edit 权限，它可能在调研时顺手改文件；如果给它 task 权限，它可能把简单问题也继续委派出去。所以需要显式限制权限，让每个角色只做它该做的事。

典型例子是：如果 Coder 有 task 权限，遇到难题时它可能不先自己处理，而是转去调 Researcher 搜索、调 Explorer 查代码。这样一来，Builder 的路由决策就被打乱了，白白消耗 Token，而且整个过程 Builder 还不知情。正确做法是：Coder 只做它能通过编码直接解决的事；一旦无法靠编码继续，就把问题交回 Builder 处理。

模型的匹配

不同任务需要不同层级的智能。最贵的模型，应该留给最需要判断力的任务。

在配置时，还应该考虑多 Provider 混用，以及故障 Fallback 方案，这两项工作用于调优中的效果对比、成本优化，以及单点故障风险降低。

上下文管理与信息隔离

上下文是最稀缺的资源，紧张的上下文窗口也会让模型效果快速下降。因此，每一分上下文窗口都应该用在刀刃上：

1. Sub-agent 只通过最终消息与 Builder 通信，中间过程对 Builder 不可见。Builder 只需要知道“任务完成了，结果是 XXX”；只有在出现意外时，才补充更详细的过程信息。

2. Compaction 可同时采用三种策略：auto（自动触发）、prune（主动修剪）、reserved（保留空间）。

第三步：增加 Plan 工作流，解决更复杂的任务

为什么先规划后执行

对于复杂任务，不加规划就直接调用 Builder 执行，会有四个常见问题：

1. 上下文窗口不够。前面已经讨论过，不再展开。
2. 缺乏全局视野。Agent 看到第一个文件就开始改，改到第三个文件才发现和前面冲突，又要回头返工。
3. 不可恢复。执行到一半上下文满了，或者中断了（断网、关机、Token 用完），进度丢失，只能从头再来。
4. 不可审查。人不知道 Agent 打算做什么，只能等它做完再看结果。方向错了，代价已经产生。

Plan-Execute 两阶段工作流能直接解决这些问题。因此我们在 Builder 之外，再增加一个专门负责制定计划的 Planner。

Planner Agent

Planner 负责接收复杂任务，输出结构化的 Plan 文件。Plan 以文件形式持久化，带来四个好处：

• 全局视野不会因上下文耗尽而丢失。
• 中断后能从文件恢复进度。
• 可以接受机器和人的 Review，可以在执行前审查和修改（human-in-the-loop）。

Planner 只能读写一个固定目录（如 ./plans/<name>.md），以物理方式保证规划与执行隔离。

Plan 文件的结构设计

Plan 文件是一个结构化的执行清单，有三个核心设计点：

Batch 思维：同一批次内的任务彼此独立，可以并行；不同批次之间有依赖，必须按顺序执行。并行能显著加速，但前提是判断清楚哪些任务真正独立——这个判断应放在规划阶段，由 Planner 负责。

Task 的五要素：

1. 指定角色：由哪个 Sub-agent 执行。
2. 描述：可执行的任务说明，包含具体文件和期望行为。
3. 涉及文件：要创建、修改或读取的文件列表。
4. 验证条件：明确的检查方式。
5. 状态标记：pending / in-progress / completed / blocked

强制的最终验证 Batch：每个 Plan 的最后一个 Batch 必须包含集成测试和最终审查。单个任务通过不代表整体正确——Task A 改了接口，Task B 还在用旧接口，各自测试都能过，合在一起就出错。

计划的执行 (Execution)

计划的执行本质上是在管理一个状态机，驱动 Plan 文件中的任务从 Pending 走到 Completed。可以通过一个简单的 Skill 描述来实现。

核心执行流程：

1. 加载 Plan 文件，扫描所有任务状态。
2. 找到第一个未完成的 Batch，开始执行。
3. 对每个任务：先标记为 in-progress 并写入文件 → 委派 Agent → 收到返回后更新状态 → 立即写入文件。
4. Batch Gate：当前 Batch 全部完成后，才进入下一个。
5. 最后执行验证 Batch

断点恢复：当发现 Plan 文件中有 in-progress 状态的任务时，说明上次执行被中断。此时恢复步骤如下：

1. 找到所有中断的任务。
2. 派 Explorer 评估损坏程度：文件是否完整？有无 TODO 占位？项目能否编译？
3. 根据评估结果处理：已完成 → Reviewer 验证；部分完成 → Coder 继续；已损坏 → Coder 修复。

核心原则：永远不要假设中断的工作已经完成。

额外的行为准则

• Scope Per Delegation：单次委派给 Coder 的任务不超过 5 个文件，超过就拆分。
• Done Means Verified：完成的标准是验证条件通过，不是"代码写了"或"任务都派完了"。
• Persist Progress Eagerly：每次状态变更立即写入文件。
• Specification Drift Check：执行完所有 Batch 后，逐字重读 Goal 和 Verification Criteria，对比实际产出，检查是否悄悄增加了功能、丢掉了需求，或行为偏离了原始要求。

进阶思路：Ralph Loop

如果项目更加复杂，需要 AI 长时间独立完成，但目标明确，可以在上面基础上引入 Ralph Loop 方法。

2026 年 3 月，Anthropic 意外泄露了 Claude Code 的全部 51.2 万行 TypeScript 源码。韩国开发者 Sigrid Jin 在两小时内用 Ralph Loop 方法，把整个代码库从 TypeScript 重写为 Python，全程没有手写一行代码，完全靠 Agent 自主迭代直到跑通。

Ralph Loop 的核心思路是：把需求拆成一组独立的需求项，每次循环只处理一条，验证通过才继续下一条；每次循环都启动全新的 Agent 上下文，迭代之间的记忆靠文件传递（git 历史、进度文件、需求状态），不依赖上下文积累，从而避免长时间执行中的上下文退化。具体流程：

1. 列出所有需求项，每条标记通过或失败。
2. 启动全新 Agent 上下文，选取优先级最高的未通过项。
3. 实现它，运行验证，通过则标记完成。
4. 把本次经验追加到进度文件，供下次迭代参考。
5. 重复，直到所有需求项通过，或达到最大迭代次数。

在实现形式上，Ralph Loop 可以是一个 Skill，被调用后由 Builder 驱动既有的 Agent Team 反复执行。

总结

搭建 Agent Team 本质上不是在写 Prompt，而是在做架构设计。和设计微服务、设计团队分工没有区别。有意思的是，当你真正开始拆分角色、划定权限、设计状态流转时，你会发现这套经验可以反过来帮你理解人类团队协作中的很多问题：为什么要有明确的职责边界，为什么流程要持久化，为什么 review 和测试不能省略。Agent 是一面镜子，照出来的是你对“如何组织工作”这件事理解到什么程度。