如果你跟我一样已经把 Claude Code 用进了日常开发里一定遇到过这种场面一个功能从需求讨论到代码落地跑了几个小时Agent 开始把前面的决定忘掉修了这个又弄坏那个。我一开始以为是上下文不够长后来发现问题更深——一个 Agent 同时扮演产品经理、架构师、程序员和测试角色一多行为就开始飘。为了解决这个问题我开始研究 Claude Code 的 Agent Teams 机制简单讲就是把它从“单兵”拆成“一队专家”让它们在同一个项目里分工协作。这篇记录了我一个多月的完整实操包括为什么这么拆、怎么配置、踩了哪些坑适合已经在用 Claude Code、想往工程化方向更进一步的人参考。1. 单Agent的瓶颈为什么我最终转向了多Agent协作1.1 上下文漂移长任务中的“即时失忆”用 Claude Code 做超过半小时的任务你会发现一个很典型的现象项目初期定的技术选型和约束会在某次修改之后悄悄走样。我做过一个带数据库的博客系统最初明确用 SQLite 和轻量 ORM结果三个小时后Agent 为了“优化一条查询”直接引入了裸 SQL把之前的架构决定破坏了。这不是模型变笨了而是上下文管理出了问题。Claude Code 的上下文窗口虽然不小但在长会话里每一次工具调用结果、每一次文件读取都会占用空间。早期讨论的细节会被压缩甚至被后续内容冲掉模型只能基于最近能看到的信息做判断。说白了它没有被“遗忘”但那些最早的决策已经不再影响它当前的注意力了。单 Agent 模式下这种漂移会随着任务时长线性放大到最后你甚至不知道该信它哪一个版本。1.2 角色混杂导致的行为不稳定很多人喜欢把一个 Agent 当全能选手用给它一大段 prompt“先分析需求再设计架构然后写代码最后写测试。”听起来高效实际上很危险。模型在一次对话里需要频繁切换思维框架行为会变得随机有时候它过度保守只给你方案不动手有时候又激进到跳过设计直接改代码。我自己遇到最典型的案例是同一个需求跑两遍第一遍它认真列出了目录结构和 API 设计第二遍直接开始改src/目录下的文件连设计文档都没生成。单 Agent 的 system prompt 再怎么强调“先计划后执行”也很难约束它长时间保持角色稳定因为“角色”本身在一个上下文里是流动的。把角色拆给不同的 Agent本质上就是把“流动的角色”变成“固定的进程边界”。1.3 什么项目值得引入Agent Teams不是所有项目都需要 Agent Teams。我刚开始接触的时候也兴奋过一阵结果给一个一次性脚本也配了四个角色纯粹是浪费时间。多 Agent 协作有它的启动成本你需要维护角色定义、配置权限、传递中间产物这些对简单任务来说都是负担。我的判断标准是下面几条至少满足两条再上 Teams项目有多个模块改动会互相影响需求会持续迭代而不是写完拉倒需要稳定的代码约束和审查流程你不是一个人在看代码未来可能有协作者接手。反过来纯 demo、一次性爬虫、临时分析脚本单 Agent 直给反而更快。Teams 解决的问题是“工程质量”和“过程可追溯”而不是“出结果的速度”。想清楚这一点才不会把协作机制用错地方。2. Agent Teams的组成结构与角色分工2.1 最小团队Planner / Coder / Reviewer / Tester一个能跑起来的团队不需要很多人我常用的最小配置是四个角色Planner、Coder、Reviewer、Tester。它们之间的协作关系很接近真实开发流程先设计再实现然后审查最后验证。角色核心职责主要产出典型权限Planner拆解需求、制定技术方案、明确边界PLAN.md、决策列表只读不允许改代码Coder按方案实现具体功能维护代码源码、实现记录可读写src/下的文件Reviewer审查代码规范、边界条件、安全问题REVIEW.md只读禁止写文件Tester编写与运行测试做回归验证TEST_REPORT.md只能执行测试相关命令这个分工不是拍脑袋想出来的它解决了单 Agent 模式下最核心的两个问题计划和执行互相干扰、写代码和审查自己写的代码天然偏心。让每个 Agent 只干一件事行为会稳定很多。2.2 角色定义文件怎么写才有效在 Claude Code 的项目目录下我会建一个.claude/agents/文件夹每个角色一个 Markdown 文件。内容不需要很长但一定要把“边界”写清楚。拿planner.md举例# 角色Planner 你是一个资深架构师负责将需求拆解为可执行的实现步骤。 你需要遵守 1. 只输出设计方案不写业务代码。 2. 每次回复必须以“决策列表”开头。 3. 禁止修改 src/ 下的任何文件。 4. 当需求不明确时一次性列出所有需要确认的问题。 5. 方案必须给出验收标准。写角色定义的要点是“负面约束”比“正面要求”更管用。光说“你要仔细审核”没有意义但写清楚“禁止修改 src/ 下的任何文件”Agent 的行为立刻就能被约束住。每个角色定义拉开层级协作时就不会越权。2.3 串行与并行两种协作模式Teams 不是把一堆 Agent 扔进一个会话里聊天那样只会乱成一锅粥。我实际用过两种稳定模式。串行模式适用于单个功能开发流程清晰Planner 产出 PLAN.md → Coder 读取并实现 → Reviewer 审查源代码 → Tester 回归验证。每一步的产物都是下一个角色的输入链路清晰出问题也好定位。并行模式适用于大版本重构比如同时改造模块 A、B、C。我会让 Planner 先拆出三份独立的子计划然后分别启动三个 Coder 各负责一个模块最后由一个 Reviewer 统审。这种情况下Planner 的角色从“出方案”变成了“协调者”它需要定期汇总各方进展。串行稳定、并行快但并行对角色定义的要求更高。如果 Coder 之间需要共享接口约定必须先由 Planner 定好接口文档否则合流的时候你会发现两个模块根本对不上。2.4 团队规模别超过5个角色我见过有人把团队配到八个角色需求分析师、架构师、后端开发、前端开发、测试、文档、DevOps、安全审计……听起来很全能实际跑起来每个 Agent 都在等别人的产出Token 消耗暴涨中间产物多到没人理。我的经验是 4 到 5 个角色是上限。每多一个角色就多一份状态同步成本多一层信息过滤的延迟。更重要的是上下文预算会被瓜分角色越多每个 Agent 能看到的关键背景就越少。如果你的需求真的需要八个角色那大概率不是 Agent 团队能解决的而是需要组织里的真人来协作。3. 实操配置从零搭建一个Agent Teams工作区3.1 环境准备Ubuntu/Windows安装与VSCode联动先说安装。Claude Code 本质上是命令行工具依赖 Node.js 环境。Ubuntu 下我一般先装好 Node.js LTS然后用 npm 全局安装。Windows 下更建议直接用 WSL省去很多路径和权限的麻烦如果你坚持用原生终端也可以但后续配置路径容易踩坑。装完以后跑一下版本命令确认能正常工作。VSCode 联动方面我不装花哨的扩展直接在 VSCode 的集成终端里启动 Claude Code这样看代码和和 Agent 交互都在同一个窗口。有一点要注意如果你在 Windows 上用原生终端Claude Code 执行 shell 命令时可能触发路径解析问题最好统一用 WSL 的 bash。安装完基础环境后先做一个最小实验在空目录里启动 Claude Code让它创建一个测试文件。这一步能确认工具调用、文件读写权限都正常再进入 Teams 配置。3.2 项目级团队配置目录与共享手册Team 配置我放在项目根目录下结构大概是这样的project/ ├── .claude/ │ ├── agents/ │ │ ├── planner.md │ │ ├── coder.md │ │ ├── reviewer.md │ │ └── tester.md │ └── settings.json ├── CLAUDE.md └── src/CLAUDE.md是这个项目的“团队宪法”所有 Agent 启动时都会读取。我会在里面写清楚技术栈、目录规范、命名约定、禁止事项。比如我会写“所有数据库操作必须走 repository 层禁止在业务代码里写裸 SQL”。这样即使不同 Agent 各自为战它们遵循的规则也是同一个版本。settings.json则负责权限和运行参数后面会详细说。3.3 启动协作切换Agent与产物交换我的启动方式是这样的先在终端里启动 Planner让它把需求拆成 PLAN.md然后关掉 Planner 的会话用另一个终端启动 Coder让它读取 PLAN.md 开始实现。每个角色都是独立会话靠文件交换中间产物。claude --agent planner 需求为项目增加一个批量重命名工具 claude --agent coder 读取 PLAN.md开始实现第 1 阶段也有人会在同一个会话里用指令切换 Agent我不推荐。上下文一旦混在一起Planner 的口吻会污染 Coder 的行为容易出现“Coder 突然开始输出设计文档”的怪事。独立会话是协作质量的基本保障。3.4 让Agent直接执行终端命令的权限边界Agent 要干活必须允许它执行命令。但直接放开所有 Bash 权限等于让一个实习生拿着管理员账号乱跑。我建议在settings.json里配置白名单和黑名单{ permissions: { allow: [ Bash(npm test), Bash(git diff), Bash(python src/rename.py --dry-run) ], deny: [ Bash(rm -rf *), Bash(git push --force) ] } }这样配置的意图很明确常规命令自动放行危险命令直接拦截。如果 Agent 碰到不在列表里的命令它会停下来要审批不会擅自执行。尤其是多 Agent 并行时你要是不设置限制某个 Coder 跑一个git clean -fdx就能把队友的产出全清掉。这个坑我踩过代价非常惨。4. 一次完整协作从需求到测试的实战复盘4.1 Planner的拆解把模糊需求变成可执行计划我拿最近做的一个“批量重命名图片文件”的功能来复盘。需求本身很模糊就一句话“写个工具能批量重命名图片。”如果让单 Agent 直接开写它大概率会拍脑袋做一套自以为是的交互方式。Planner 接手后在 PLAN.md 里输出了这样的决策列表语言选 Python因为跨平台且生态成熟交互方式用命令行 CLI不做 GUI重命名规则支持两种前缀/后缀追加以及正则替换必须支持--dry-run模式先预览结果再实际执行目标文件已存在时提供“跳过/覆盖/终止”三选一新增tests/test_rename.py覆盖核心逻辑。每个决策后面都标了理由和验收标准。这份 PLAN.md 不只是给 Coder 用的也是后面 Reviewer 和 Tester 的参考基准。4.2 Coder的实现与Planner的纠偏Coder 按 PLAN.md 动手后遇到了一个计划里没覆盖到的点用户输入了一条非法正则表达式应该报错还是自动忽略按照我最初的设定单 Agent 很可能直接让程序崩溃或者吞掉错误。但 Coder 这里做了正确的事——它没有擅自决定而是在实现记录里标了一个[需确认]交回给 Planner。Planner 补充了规则正则以编译失败时向用户提示具体错误位置并终止执行。于是 Coder 写出了类似这样的核心逻辑def build_rename_map(paths, pattern, replacement): try: regex re.compile(pattern) except re.error as e: raise ValueError(f无效的正则表达式: {e}) mapping {} for path in paths: new_name regex.sub(replacement, path.name) if new_name ! path.name: mapping[path] path.with_name(new_name) return mapping这个“Coder 提问 → Planner 补充决策 → Coder 实现”的循环是 Teams 协作最值钱的部分。它把不确定性挡在了实现之前而不是让错误一路滚到测试阶段才被发现。4.3 Reviewer的审查规范与边界条件Coder 完成实现后轮到了 Reviewer。它不需要跑代码但会逐行审查源码和 PLAN.md 的匹配度。Reviewer 这次发现了一个值得记录的问题问题级别高 位置src/rename.py:42 描述目标文件存在时直接抛出 FileExistsError与 PLAN.md 中“跳过/覆盖/终止”的交互策略不符。 建议改为询问用户选择dry-run 模式下只输出冲突列表。这个发现非常典型。Coder 为了实现简单把异常直接抛给用户但产品设计里要求的是可控交互。没有 Reviewer 这一步这个功能上线后用户只能看到一堆晦涩的报错。Reviewer 的产出是一份 REVIEW.mdCoder 再根据它修复。4.4 Tester的回归验证功能没有破坏旧行为最后是 Tester。它会读取 PLAN.md 和 REVIEW.md写测试用例并运行。这次它覆盖了四类场景正常重命名、前缀/后缀追加、正则替换、目标文件冲突处理。Tester 第一次运行测试就抓到了一个回归旧的“文件名排序”逻辑在处理中文文件名时顺序不稳定新代码没有调整比较函数。它把问题提交给 CoderCoder 修复后Tester 再次运行全部用例直到输出一份绿色的测试报告。到这里这个功能才算是真正完成了。整个流程走完项目里留下的不是一团模糊的对话记录而是一组清晰的文档PLAN.md、REVIEW.md、TEST_REPORT.md。这对项目后期接手的人来说价值比任何聊天轮次都高。5. 常见坑与排查经验5.1 企业策略禁用订阅访问时的处理很多公司环境里运行 Claude Code 会报这么一句错your organization has disabled claude subscription access for claude code。这不是网络问题也不是代码问题而是组织策略在管理后台关闭了 Claude Code 的订阅访问通道。遇到这个报错你需要走内部流程找管理员确认权限个人这边没有太多技术手段可以绕开。如果你是自己想继续实验另一个思路是让 Claude Code 接入本地模型比如通过 LM Studio 启动一个 OpenAI 兼容的本地端点然后在环境变量里指定模型地址。我试下来的感受是本地模型在简单任务上够用但 Agent Teams 对模型的指令遵循和工具调用稳定性要求很高本地模型容易出现“角色跑偏”或者“跳过工具直接编结果”的问题。所以本地模型这条路我建议只用来做低风险的探索真正的主力开发还是走官方订阅通道更靠谱。5.2 Agent互相“吵架”上下文隔离与信息同步我第一次把多个 Agent 放进同一个会话里协作结果它们开始反复争论一个接口命名问题A 说用rename_filesB 说用batch_rename两边各自引经据典一轮轮互相覆盖。最后我把会话停了。后来我才想明白多 Agent 协作不是让它们“聊天”而是让它们“交接文件”。每个 Agent 的会话必须是独立的信息只能通过 PLAN.md、REVIEW.md 这种中间产物来传递。一旦你允许两个 Agent 互相引用对方的完整对话上下文它们就会开始“吵架”因为每一方都会把对方的输出当作需要纠正的对象。解决办法很简单物理隔离会话只保留必要的产物在磁盘上。5.3 命令权限太宽引发的意外这是我在并行开发里真实踩过的坑。当时为了省事我给了某个 Coder 全部 Bash 权限结果它在清理临时文件时执行了rm -rf temp/*而temp目录因为符号链接问题指向了src/直接把两个模块的源码删了个精光。虽然代码有 git 历史但那一整天的工作成果全丢了。所以我在权限配置上越来越保守。首先deny列表必须包含所有带rm -rf、git reset --hard、git push --force等危险操作的命令其次allow列表尽量收敛到测试、构建、diff 这类只读或副作用可控的操作。优先级永远是安全大于效率Agent 多跑一步没关系项目崩了才是大麻烦。5.4 成本失控如何管住多Agent的Token消耗多 Agent 协作的成本是单 Agent 的数倍因为每个角色都要读取CLAUDE.md、项目结构、中间产物。我一开始没注意跑了一个月账单涨得很明显。后来我总结了几条省钱经验。第一Planner 的输出用“决策列表”而不是长文分析能把 PLAN.md 的体积压到原来的三分之一第二给每个 Agent 设置最大回复步数避免它在某个问题上无限自我纠结第三Reviewer 只看 diff不要让它读整个文件——用git diff的输出作为输入Token 消耗能省很多。第四不是每个阶段都必须四件套齐全小改动可以只跑 Coder Tester把 Planner 和 Reviewer 留到关键节点。按这套方式调整后我的实测用量降了大概三成质量没有明显下降。把 Agent Teams 真正跑起来之后我的感受是它并没有让每个决策变得更聪明但让整个工程的决策变得可追溯、可回滚。Planner 留下的 PLAN.md 和 Reviewer 的审查记录现在成了项目里最值钱的文档。如果你也在用 Claude Code 做大一点的项目个人建议先别急着堆角色先把 Planner 和 Coder 这两个角色的边界划清楚你会立刻感受到差别。