用 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 是一面镜子，照出来的是你对“如何组织工作”这件事理解到什么程度。

更稳妥的做法是把选型当作流程设计：先将工作流拆解为若干明确场景（如日常问答、深度研究、代码执行、评审与合并等），再为每个场景匹配最合适的工具与模型，而不是寻找万能解。能让决策具备可解释性、可替换性与长期稳定性————即便具体产品更迭频繁，框架仍然有效。

因此在选型中，我建议三步走：明确工具职责边界 → 按任务匹配模型能力 → 设计分层采购与冗余。下面的组合基于 2025 年末至 2026 年初的个人经验。

通用 AI 助手：问答与研究

这类工具不直接进代码仓库，负责的是日常问答、资料查找、以及需要较长链条的深度研究。把它们和研发执行工具分开看，后面的选型判断会清楚很多。

研发工具（IDE/CLI）：执行与交付

进入研发主流程后，需要的是能直接接触代码、仓库和评审流程的执行工具。这一层决定的是交付效率。

OpenCode 的要点在于配置 oh-my-opencode 插件。这是一个基于多 Agent 协作的系统。设计理念采用精细角色分工，虽然导致 Agent 间交互频繁、任务链条较长，Token 消耗大，但带来了复杂技术场景下的交付质量保障。熟悉交互模式并为不同角色匹配合适的模型后，能够实现数小时持续自主的深度技术讨论。

GitHub Copilot 的 Web 版代表另一种路径：高度集成、场景封闭，追求端到端自动化。它刻意减少多轮深度交互，更关注从问题描述到代码合并的一站式解决。对于边界清晰的中等复杂度任务，其效率极高，并与 GitHub 研发评审流程无缝集成，使用体验接近为开源项目做全流程代码贡献。

两者各有侧重：OpenCode 重视可控性和深度，GitHub Copilot 追求自动化闭环。实际中经常配合使用，比如复杂架构讨论选 OpenCode，具体 bug 修复用 Copilot。

模型选择：按场景匹配能力

工具确定后，下一步是为不同任务场景匹配模型。

其中 领域/业务理解 比较特殊：这类任务完全依赖用户提供的上下文（业务文档、历史代码、决策记录等），模型预训练知识反而容易引入幻觉。因此对模型选择不敏感，上下文窗口够长即可。

除领域理解外，按典型场景可分配不同模型与策略：

补充一点使用体感供快速建立预期：Opus 是经验丰富的高水平工程师，输出仍需端到端验证；GLM-5 是水平和稳定性都次一档的工程师；Kimi K2.5 和 MiniMax M2.5 更像极便宜的实习生，只能在确定性任务中可靠工作；Claude Sonnet / Haiku 的能力与性价比在国内市场有大量更优平替，通常没有使用必要。

云服务采购

模型和工具选定后，最后要解决的是怎么买。核心判断：不要把预算押在单一供应商上，按任务风险等级分散采购，关键路径留冗余。

结语

效率提升不在于追求最强模型，而是持续拆解工作流、按场景匹配工具与模型。起步不需要一步到位——先把通用 AI 助手和研发执行工具分开，区分使用场景，就已经比凭直觉选型好很多。后续再根据实际痛点和预算细化模型分工与采购策略即可。值得注意的是，多工具、多模型的组合本身有切换成本和学习曲线，需要预留时间适应。

这种情况，如果只是持续一周，那还可以看作一时忙碌。如果连着几个月都这样，就需要跳出来换个方式解决问题了。

为什么？

互联网行业节奏太快，所以事情做不完不会单独一周的问题：组织在不断调整和发现新的增长点，试错和调整节奏快，业务结构和依赖复杂。因此，需求产生的速度天然高于个人消化的速度，越追只会越慢。最终陷在事务中，无法发掘新的价值和增量。

既然做不完，关键就不是怎么做完，而是判断做哪些、不做哪些，让自己能抽身去并行考虑长期高价值工作。

那么具体怎么跳出？我的建议，是围绕一份工作准则文档解决问题。下面讲的，就是这篇文档应该写什么、为什么写、以及怎么用。

怎么做？

要写的文档并不复杂，可以叫做《工作准则》，或者柔和一些的《XXX使用手册》。链接可以放在团队Wiki里，也可以放在聊天软件签名中，让需求方人人能看到。

第一节：定义职责范围。讲清自己负责什么、不负责什么。确保需求方能快速判断，是否找到了正确的人。

第二节：顺序排列短期需求。这是需求方最关心的一部分。

首先要根据自己的情况，按类型说明优先级原则，比如，线上故障 > 已承诺的业务交付 > 阻塞他人的协作项 > 新业务需求 > 内部优化和探索性工作。这样就做好了总排序。

然后是同类需求内，按价值和紧急程度排序，并放入下表之中：

注意以下四点：

1. 排序的最关键因素是“价值估计”一列。如果一件事没有价值，光是紧急，并没有解决的意义；
2. 排序承诺的是交付顺序，也就是承诺前面的事情一定会在后面事情前完成，但并不是说所有事情最终都能做完；
3. 预期交付时间一定要有一个估计，要留有一点余地，原因是你可能还会临时接到更高优先级的需求；
4. 当新需求进来时，按原则重新调整顺序和交付时间，并通知被影响的人。

第三节：留出高价值工作专有时间。短期需求自带紧迫感，一旦做不完短期需求，就永远没有时间做长期高价值工作。因此文档里要明确写出长期事在什么时间做。常见有两种方法：

1. 每天留出固定两小时；
2. 每周留出固定一两天。

一定要按比例守住高价值工作的投入时间下限。如果高价值工作投入不够，在下一天/下一周开始时，必须优先补上。

第四节：顺手做超短期事。对于十分钟内能解决、不需要切换上下文的事，可以当场做掉。这个十分钟是参考值，可以按自己的情况调整，但必须有一个明确数字，否则所有事都会被归入顺手。对于必须当天处理的顺手事，可以承诺集中在下班前一个固定时段开始处理。

写完以上四节，工作准则文档就完成了。

公开

原则如果无法取得共识，矛盾则会继续。但原则公开之后，局面就反过来。只要原则有合理性，提需求的人会先看第一节，做一轮自我筛选，再结合第二节理解你给出排期原因和预期交付时间。

对方如果坚持自己的需求更重要，就需要解释为什么应该插队，这就必须和排在前面的所有需求逐一PK，而不再由你解释为什么交付慢。让论证的责任倒置。这种做法，还能更有理有据地避免老板给你临时加上不重要的事。

应用

陷在执行里的人常有一个共同的毛病：来事就接，不分轻重。碰到事的第一反应永远是"这件事是怎么回事，我应该怎么解决"；却回避了思考”这件事该不该做，有多重要，什么时候做“。

所以凡遇事要做到：

1. 花精力彻底弄清，这件事在文档里属于哪一节和哪一类，应该如何确定顺序。这需要围绕文档确立的原则，进行沟通、深入了解事情、并对需求方做必要的解释；
2. 分析文档中，不够适合现状的地方，持续优化文档和原则，逐步把例外变成常例，让常例更有效。

衡量

还需要一组指标来检查它是否真在生效。我建议分三层看，从低到高：

三层是递进的。但真正要看的是价值层，上面两层是出问题时用来定位是哪一环失效的：只看执行层会误判，因为高吞吐可能只是在快速处理低价值需求；只看结构层也不够，长期事的时间花到了，不等于做出了新东西。

结尾

写这页文档之前，你和需求方之间没有共同的依据，每次新需求来都要从头谈一次优先级。文档挂出去之后，争议有了可以对照的规则，沟通从一对一的反复解释变成了围绕同一份原则的取舍。事情依然做不完，但被推着跑的状态会停下来，人能跳出来看价值。