在企业项目里使用 AI 编程助手或 Agent 时很多人很快会碰到一个分水岭单次对话能解决局部问题但遇到“先调研、再反证、最后汇总”这类多阶段任务单个 Agent 的输出质量和可信度会明显下降甚至出现前后自相矛盾的情况。Agent Teams 的思路是把任务拆给多个角色让不同 Agent 分别承担调研、反证、汇总等职责再用提示词约束行为、用统一文件格式传递结果、用验收清单判断本轮是否通过。这篇文章围绕 Claude Code 环境下的 Agent Teams 多智能体协作以一个企业需求调研项目为例子完整演示角色分工、提示词设计、任务编排、运行命令和验收方式让读者能直接复制到自己的项目里。1. 先理解 Agent Teams 为什么能改善多阶段任务的质量1.1 单 Agent 的自我一致性陷阱单个 Agent 在回答复杂问题时天然倾向于维持“叙事一致性”。也就是说它一旦在开头给出了某个结论后续内容会尽量向这个结论靠拢很少主动推翻自己。这个问题在做调研类任务时尤其明显让同一个模型既负责收集资料、又负责审查自己的结论审查环节基本会变成走过场。另一个问题是上下文污染。调研、反证、汇总三个阶段对上下文的要求不同。调研阶段希望大量读取资料、提取事实反证阶段希望跳出资料本身找漏洞汇总阶段则希望同时看到事实和质疑。全部放在一轮对话里前面阶段产生的中间推理会干扰后面阶段的判断。Agent Teams 的解决办法很直接把三个阶段拆成三个独立执行单元每个 Agent 只拿到上一轮的结构化输出重新开始推理。1.2 角色拆分调研、反证、汇总各自的职责边界在企业场景里这三个角色的职责可以这样定义调研 Agent 负责“打开视野”。它的目标是尽可能覆盖相关事实、数据和观点并把“事实”和“个人推断”分开标注。反证 Agent 负责“收窄可信度”。它的目标是找反例、找逻辑漏洞、找被忽略的前提条件。它不需要提出新方案只需要说明“在什么条件下前面的结论会不成立”。汇总 Agent 负责“收敛决策”。它同时拿到调研报告和反证清单剔除已经被证伪的内容保留经过检验的结论并输出带前提条件的建议。这三个角色不是简单的前后串联而是有明确的检查点。调研产出要能回答“有什么”反证产出要能回答“哪里不可靠”汇总产出要能回答“在什么前提下可以怎么做”。1.3 什么场景不需要上 Agent TeamsAgent Teams 并不是所有任务都适合。简单问答、单文件代码生成、格式转换这类任务拆成多个 Agent 反而增加成本和延迟。任务类型单一 AgentAgent Teams单文件代码生成合适直接对话即可过度设计多阶段需求调研容易片面、自相矛盾合适代码审查能发现问题但缺少交叉验证更合适简单知识问答合适过度设计技术方案选型评估输出主观性强合适判断标准可以简化为两条任务是否跨多个认知阶段结论是否必须经过质疑和验证。只有两条都满足时才值得为 Agent Teams 付出编排成本。2. 环境准备Claude Code 安装、认证与权限控制2.1 安装前置条件与版本确认Claude Code 是 Anthropic 提供的命令行工具用于在终端里与 Claude 模型协作。安装前建议先确认本机状态。下面的命令在多数环境里通用具体版本要求以官方文档为准。node -v npm -v如果node或npm没有安装需要先安装 Node.js。常见要求是 Node.js 18 以上但版本会随工具更新而调整建议安装前到官方文档确认。还需要确认账号具备使用权限。使用方式分为登录态认证和 API Key 认证两种。学习环境推荐先登录账号生产环境推荐用独立的 API Key 并通过环境变量注入。2.2 安装、登录与 Windows 安装报错安装命令通常是npm install -g anthropic-ai/claude-code安装完成后验证claude --version如果输出版本号说明安装成功。接下来完成认证claude login也可以使用 API Key 方式export ANTHROPIC_API_KEY你的_api_key这里要注意的是环境变量只在当前终端会话生效生产环境应该写入 CI 或密钥管理服务不要写进代码仓库。Windows 下最常见的安装问题来自 PowerShell 执行策略。现象是执行命令时提示“无法加载文件……因为在此系统上禁止运行脚本”。可以先查看策略Get-ExecutionPolicy临时调整为当前用户允许本地脚本Set-ExecutionPolicy -Scope CurrentUser RemoteSigned还有一种情况是npm install报EACCES权限错误这通常是因为全局 npm 目录属于其他用户。推荐用 nvm 管理 Node 版本避开全局目录权限问题。2.3 关键配置项与权限最小化Claude Code 本身支持在项目目录中维护配置文件。以常见设计为例可以把模型选择、目录权限、输出格式等放在配置里但具体字段要以当前版本帮助为准{ model: claude-sonnet-4-20250514, permissionMode: acceptEdits, allowedTools: [Read, Glob, Grep, Bash], disallowedTools: [Write, Edit], includeCoT: false }配置里的要点是权限最小化。调研、反证、汇总三个 Agent 大多数情况下只需要读取输入文件、执行少数只读命令、向指定输出目录写入结果不需要修改项目源代码。如果整个流程写着写着开始改动仓库里的业务文件事故就不远了。2.4 生产环境部署前要补齐的能力学习环境跑通后进入生产环境之前需要补齐这四件事日志审计每个 Agent 的输入提示词、输出文件、模型版本、执行时间都要落盘。没有日志后续定位问题只能靠猜。密钥管理API Key 不能出现在命令行参数里。使用环境变量、CI Secret 或专门的密钥管理平台。成本控制多 Agent 意味着多次模型调用。要限制单轮输入长度、设置最大 token、控制并发数避免一次编排任务消耗失控。模型版本固定生产环境要锁死模型版本。如果模型版本不固定今天跑通的提示词下周可能因为模型更新而输出结构变化。注意不要只验证 Agent 能启动、能输出还要验证输出文件的格式是否符合后续 Agent 的输入要求。编排链路里格式不一致的失败率远高于内容质量失败的频率。3. 企业需求调研实战调研、反证、汇总三 Agent 的提示词设计3.1 项目背景与三 Agent 分工表假设当前任务企业要在现有产品中评估“是否新增一个客户自助服务模块”。这个需求涉及业务背景、技术成本、客户价值、风险等多个维度不能只靠一轮对话给出结论。三个 Agent 的分工如下Agent输入输出验收标准调研 Agent需求说明、资料包事实清单、推断清单、待确认项每条事实都有来源推断单独标注反证 Agent调研报告质疑清单、风险点、验证方式质疑必须给出具体条件和验证路径汇总 Agent调研报告 质疑清单最终报告、前提条件、决策建议覆盖全部输入结论标注适用边界每个 Agent 的提示词单独放在prompts目录方便版本管理和复用。3.2 调研 Agent先收集事实再谈推断调研 Agent 最容易失控的地方是“把推断包装成事实”。所以提示词里要强制分离事实、推断和待确认项。# 角色 你是企业需求调研 Agent。你只负责收集和分析输入资料不负责做最终决策。 # 任务 阅读 data 目录下的需求说明和参考资料回答 1. 客户自助服务模块的核心诉求有哪些 2. 当前系统里哪些能力可以直接复用 3. 行业或历史资料中有哪些可参考的落地案例 # 输出格式必须严格遵守 ## 事实清单 - 每条事实单独一行格式事实内容来源文件、来源段落 ## 推断清单 - 每条推断以[推断]开头说明推断了什么、依据是什么 ## 待确认项 - 列出资料中没有覆盖、需要业务方确认的问题 # 禁止事项 - 禁止编造资料中不存在的数字和案例 - 禁止把推断写成事实 - 资料不足时必须写入待确认项不能硬凑结论这段提示词的关键在于输出格式被固定成三块。后续反证 Agent 拿到的是结构化的内容而不是一段自由文本。限制 AI“说假话”不是靠一句“你要诚实”而是靠强制标注来源和推断让没有依据的内容无处藏身。3.3 反证 Agent把“质疑”变成“可验证条件”反证 Agent 的常见问题不是太严格而是太松散。它经常输出“这个方案可能有风险”这类空话。所以提示词里必须要求每条质疑都要给出“在什么条件下会怎样”以及“怎么验证”。# 角色 你是反证 Agent。你的任务是找出调研报告中不成立、不完整、过于乐观的部分。 # 输入 读取 outputs/01_research.md 的调研报告。 # 输出格式必须严格遵守 ## 致命问题 - 每条格式结论 | 失效条件 | 证据或依据 | 验证方式 ## 待澄清问题 - 每条格式疑问 | 为什么重要 | 需要谁确认 ## 可保留结论 - 明确说明哪些结论经得起推敲 # 要求 - 禁止写可能存在风险这类无具体条件的质疑 - 质疑必须基于资料、逻辑或常见工程约束 - 如果某条结论在特定条件下才成立请明确写出该条件这种设计把“反证”从主观态度变成了结构化检查清单。反证 Agent 没有权限修改调研结论它只输出质疑最终取舍交给汇总 Agent。3.4 汇总 Agent收敛结论并标注前提汇总 Agent 是流程的出口它的输出质量直接决定这次 Agent Teams 协作的价值。提示词里要强调“综合判断”而不是“平均观点”。# 角色 你是汇总 Agent。你负责综合调研报告和反证质疑输出可供业务方讨论的最终结论。 # 输入 - outputs/01_research.md调研报告 - outputs/02_challenge.md反证质疑清单 # 输出格式 ## 核心结论 - 用 3 到 5 条说明做什么、不做什么、在什么前提下做 ## 关键风险 - 结合反证 Agent 的致命问题说明应对方式 ## 待确认事项 - 列出需要业务方或技术负责人拍板的问题 ## 建议清单 - 下一步行动按优先级排序 # 要求 - 被反证 Agent 证伪的结论不得出现在核心结论中 - 每条结论必须标注适用前提 - 不要为了追求完整而堆砌所有观点汇总 Agent 承担的是“负责人的角色”它不重新做调研也不重复质疑而是基于前两个 Agent 的产物做决策支持。3.5 统一输出格式与目录结构三个 Agent 能高效协作的前提是文件格式统一。建议目录结构如下agent-team-demo/ ├── data/ │ ├── requirements.md │ └── reference/ ├── prompts/ │ ├── 01_research.md │ ├── 02_challenge.md │ └── 03_summary.md ├── outputs/ │ ├── 01_research.md │ ├── 02_challenge.md │ └── 03_summary.md └── run_agents.shdata目录存放原始输入prompts目录存放提示词outputs目录存放各 Agent 的产出。不要把所有文件混在一起否则后面排查问题时要花大量时间确认某个结果到底是谁生成的。4. 用一条命令跑通三个 Agent 并完成验收4.1 创建项目目录和输入资料先创建目录结构mkdir -p agent-team-demo/{data,prompts,outputs} cd agent-team-demo把需求说明放入data/requirements.md把参考资料放入data/reference/。输入资料一定要在运行前准备好因为调研 Agent 的内容边界完全由资料决定。4.2 编写运行脚本串起三个 Agent创建一个run_agents.sh按顺序执行三个 Agent。下面脚本用于说明思路具体 CLI 参数以自己的claude --help输出为准。#!/usr/bin/env bash set -e project_dir$(cd $(dirname $0) pwd) cd $project_dir echo [1/3] 调研 Agent 执行中 claude -p $(cat prompts/01_research.md) outputs/01_research.md echo [2/3] 反证 Agent 执行中 claude -p $(cat prompts/02_challenge.md) outputs/02_challenge.md echo [3/3] 汇总 Agent 执行中 claude -p $(cat prompts/03_summary.md) outputs/03_summary.md echo 完成请查看 outputs/03_summary.md执行前赋予脚本执行权限chmod x run_agents.sh ./run_agents.sh这里要注意两点。第一三个 Agent 必须按顺序执行反证要等调研完成汇总要等两个输入都存在。第二set -e让脚本在某个步骤失败时立即停止避免拿着残缺结果继续往下跑。学习环境可以先跑通生产环境建议把这三步拆成 CI 流水线里的独立 Job每步都要有日志和失败告警。4.3 验收清单判断本轮是否通过跑完之后不能直接看汇总报告就收工。建议按验收清单逐项确认检查项检查方式通过标准事实有来源抽查调研输出中的引用每条事实都能回溯到 data 目录资料推断有标注查看调研报告中的推断清单推断与事实分离不混写反证有依据检查质疑清单是否给出条件不是“可能有问题”而是“在X条件下会Y”汇总覆盖全部输入对比三份文件最终报告覆盖调研和反证的主要观点结论有边界检查汇总报告中的前提每条结论都标注适用条件格式可复用确认输出文件能作为下一步输入字段完整Markdown 标题顺序一致如果验收不通过不要修改汇总输出硬凑而应该回退到对应环节重新执行。4.4 多轮反证把低质量输出挡在下一轮之前第一轮跑通只是起点。实际项目中调研 Agent 的第一版输出往往有很多漏洞反证 Agent 的第一版质疑也可能不够尖锐。可以把流程设计成可循环的第一轮调研产出 - 反证产出 - 汇总产出。第二轮把第一轮的反证质疑清单追加到调研 Agent 的输入里要求针对质疑逐条补充证据或者新增一个“再审 Agent”专门复查第一轮汇总报告。多轮反证的成本是 token 消耗翻倍收益是结论可信度明显提高。建议先把第一轮跑通确认输出格式稳定后再增加循环否则排错会非常困难。注意Agent 协作的价值不在于让模型生成更多文字而在于让不同的推理阶段互相制衡。反证 Agent 的存在就是为了让调研 Agent 的不严谨处暴露出来这是单一 Prompt 做不到的。5. 从现象定位问题Agent 协作常见坑与排查路径5.1 输出偏离主题且越写越远现象调研 Agent 输出了大量与本次需求无关的行业背景或者自己发明了资料里不存在的案例。排查顺序检查data目录里是否混入了无关资料。Agent 会把输入资料当作权威依据如果资料包本身很杂输出自然跑偏。检查提示词里是否明确写了“只基于 data 目录资料”和“禁止补充外部猜测”。缺少边界约束模型会自动调用常识补全。检查输出文件是否完整落盘。如果输出被截断可能只是文件写入失败不是内容问题。解决方案是在提示词里增加更硬的约束比如“如果没有资料支撑必须在待确认项中说明不得自行补全”。5.2 三个 Agent 结论互相矛盾现象调研报告说方案可行反证清单认为存在致命问题汇总报告仍然建议推进。排查顺序先确认反证 Agent 的输入是否正确传递。很多矛盾源于反证 Agent 读取的是旧版调研报告。再确认三个 Agent 是否使用同一套数据格式。如果调研输出用了“结论A”反证输出却引用“结论A原文”说明字段命名不一致。最后检查汇总 Agent 的提示词是否包含“被证伪的结论不得使用”这一规则。没有这条规则汇总 Agent 会试图调和矛盾而非取舍矛盾。这类问题的根源通常是编排设计问题而不是模型能力问题。统一输入模板、固定字段命名、明确取舍规则能解决大部分矛盾。5.3 命令执行、认证和权限链路问题常见的报错和对应处理方式如下错误现象常见原因检查方式处理建议claude: command not found安装未完成或 PATH 未配置执行claude --version重装或重新加载 shellAuthentication failed或 401登录态过期或 API Key 无效执行claude login检查环境变量重新认证更新密钥PowerShell 禁止运行脚本执行策略限制Get-ExecutionPolicy设置为 RemoteSignedEACCES权限不足npm 全局目录权限问题检查 npm 全局路径使用 nvm 管理 Node脚本中途无输出任务过大或网络波动查看输出文件是否为空拆分任务增加超时重试排查时有个原则先确认输入是否正确再查路径和命名然后看认证和权限最后才怀疑模型本身。很多问题看起来像“模型乱写”实际是文件路径传错了。5.4 超时、Token 消耗过高现象Agent 执行时间过长或者一次编排任务消耗了大量 Token。原因通常是输入太大、输出要求过长、或者循环轮次过多。处理方式在提示词中限定输出长度比如“每条结论不超过 50 字”。将大文件拆分后再送入。整个资料包一次性塞进上下文既浪费 Token 又降低准确性。为每个 Agent 设置独立的 Token 上限和超时时间。控制多轮反证的轮次。每轮都要有明确目标不建议设置“直到无质疑”这种无终止条件。6. 让多 Agent 流程可复用版本管理、验收模板与生产化建议6.1 把提示词当代码管理提示词是这个流程的核心资产必须纳入版本管理。建议在每个提示词文件头部记录元信息!-- agent: research version: 1.2.0 model: claude-sonnet-4-20250514 updated: 2025-06-10 change: 增加事实与推断分离要求 --修改提示词后要重新跑一次整个流程验证输出结构没有变化。提示词的改动对下游 Agent 影响很大不要只改一个文件就提交。6.2 可复用验收清单模板把本文的验收逻辑整理成通用模板每次项目执行时复制一份## 本轮验收记录 - 项目/任务编号 - 执行日期 - 模型版本 - 输入文件 - 输出文件 ## 验收项 - [ ] 调研输出中每条事实都有来源 - [ ] 调研输出中推断与事实分离 - [ ] 反证输出中每条质疑都有失效条件 - [ ] 反证输出没有空泛的“可能有风险” - [ ] 汇总输出覆盖调研与反证的主要观点 - [ ] 汇总输出中被证伪的结论未出现 - [ ] 汇总输出每条结论标注适用前提 - [ ] 三份输出文件格式一致可继续作为下一轮输入 ## 结论 - 通过 / 不通过 - 不通过原因 - 需要重跑的环节这份模板可以直接放进项目的docs/acceptance_template.md每个任务复制一份填写。6.3 从需求调研扩展到代码审查与文档维护同样的三 Agent 模型可以迁移到其他场景代码审查场景审查 Agent 读代码反证 Agent 找边界条件和并发问题汇总 Agent 输出修改建议。技术选型场景调研 Agent 收集候选方案资料反证 Agent 对每个方案找反例汇总 Agent 输出带约束条件的推荐。文档维护场景调研 Agent 识别文档中过时内容反证 Agent 对照代码验证汇总 Agent 生成待修改清单。这些场景的提示词结构和验收清单可以复用只需要替换领域术语和输出字段。6.4 学习环境到生产环境的迁移清单学习环境跑通后不要直接把脚本原样搬到生产。迁移前逐项确认检查项学习环境生产环境密钥管理本地登录或临时环境变量CI Secret、密钥管理平台日志终端输出落盘、采集、告警权限当前用户完整权限最小权限、只读目录、审计模型版本跟随最新版本固定失败处理脚本中断重试、告警、回滚成本控制手动观察Token 限额、并发限制结果验收人工查看自动化校验文件格式和字段最后给新手一个练习建议先不要急着做三 Agent先把两个 Agent 跑通——调研和反证汇总先用眼睛看。确认这两个角色的输出稳定、格式一致之后再加汇总 Agent。循序渐进比一次搭好完整流水线更容易积累排查经验也更能理解每个提示词约束到底在解决什么问题。