★ FEATURED ARTICLE 把一个大任务交给 Claude Code 一个会话从头跑到尾看起来省事实际是灾难的开始。上下文越拖越长前面改过的东西后面忘得一干二净一个文件改到一半又开始琢磨另一个模块的事最后你盯着终端看它跑完一场马拉松拿到手的代码却支离破碎。这也是我后来一门心思研究 Claude Code 多 Agent 玩法的原因。标题里提到的 Agent View 和 Agent Teams一个是观察窗口一个是组织方式配合起来就是一套完整的并行作业体系。下面这篇东西我会从你到底需不需要它讲起把两个功能拆开说清楚再用一个叫 Polter 的真实项目演示一套可以照抄的流程。1. 先想清楚你到底需不需要多 Agent很多人一听说 Claude Code 支持并行、支持 subagent立刻就开始拆任务结果拆完发现比单线程还慢。原因很简单不是所有任务都适合多 Agent。这一章先帮你建立判断标准免得后面瞎折腾。1.1 单 Agent 处理大规模任务时的三个痛点先说清楚我为什么放弃一个线程跑到底的做法。单 Agent 模式处理小任务完全没问题比如给这个函数写单元测试把这个文件从 JavaScript 翻译成 TypeScript一个会话几十分钟内解决。但任务一旦变大三个问题就绷不住了。第一是上下文衰减。Claude Code 的上下文窗口再大也是有限的一个长会话跑到后面早期读过的代码、定过的方案会被挤出注意力范围。我碰过最典型的情况它前面刚确认要遵循某个命名规范跑到第二十一个文件时又开始用旧命名而且完全不自知。第二是任务切换的隐形损耗。一个会话里塞五件事每切换一次模型都要重新理解新任务的背景。这个损耗平时看不出来但累积起来非常可观。你让它改完 A 模块再修 B 模块的 bug 再补 C 的文档它花在来回切换上的 token 可能占了总量的三成。第三是单点失败风险。长任务跑到一半如果 session 断了、网络抖了、或者上下文溢出全盘重来。这个代价太痛了。1.2 什么任务适合拆给多个 Agent判断标准其实很朴素我一般看三个条件。模块边界是否清晰。任务能按文件目录、按服务、按功能模块切成分块每个块相对独立这是最基本的前提。比如一个大仓库里有用户服务、订单服务、支付服务三个服务之间只通过接口通信那天然就能拆成三块。任务间是否无强依赖。A 任务的产出不需要等 B 任务完成才能开始。比如写接口文档和写接口测试可以并行因为都基于同一份接口定义但重构数据库层和基于新数据库层改业务代码就不能并行后者依赖前者的结果。是否有独立验证方式。每个 Agent 干完活后能独立判断自己干得好不好不需要等别人验收。比如跑测试typechecklint这些是干净的验证手段。如果任务的验证必须靠另一个 Agent 的结果那就别拆。1.3 什么样的任务永远不该上多 Agent这一节是重点因为大部分人都是在这儿踩坑的。全局架构调整不要拆。比如整个项目的目录结构重新规划、核心数据模型变更、跨模块的接口协议修改这种任务需要保持全局一致性拆给多个人各自为政最后合出来的一定是四不像。需要统一上下文的代码生成不要拆。比如要生成一套风格严格统一的文件头、错误码规范、公共组件的 API 设计这种活儿一个人一口气干完反而更好。任务数量少但关联紧密的不要拆。两三个任务互相咬得很紧拆了以后 Agent 之间要来回传话成本比单线程还高。记住一个原则多 Agent 是给大规模并行拆解用的不是给小任务强行分工用的。2. Agent View 到底怎么看运行视图里的门道多 Agent 跑起来以后第一个让你头大的问题就是我怎么知道现在到底发生了什么。Claude Code 里看多个 Agent 的运行状态靠的就是 Agent View。这一章我把我自己的读图方法讲给你。2.1 Agent View 的界面构成从上到下每一行的含义我先用大白话描述一下我使用版本里的 Agent View 大概长什么样。它不是一个只有一个进度条的东西而是一个把正在运行的 Agent 全部列出来的视图面板每个 Agent 一行核心信息按列排开。Agent 名称是最左边的第一列对应你拆出来的任务名比如refactor-db、api-rewrite、test-suite。第二列是状态常见的有queued排队中、running执行中、waiting等待中、done完成、failed失败。第三列是当前动作比如正在编辑哪个文件、正在执行哪条命令、正在搜索什么内容。第四列是 token 使用量记录这个 Agent 目前吃了多少。有些版本还会显示文件变更数、执行时长、当前所在的步骤编号。我第一次用的时候只盯着状态列看后来发现最该盯的是当前动作这一列。它才真正告诉你 Agent 卡在哪、在做啥。running这个状态信息量很低running底下到底是顺利批处理还是在反复重试同一个操作差别巨大。2.2 从等待到完成Agent 状态流转是怎样的理解状态流转比记界面布局更重要。拿我观察到的典型流程来说。一个 Agent 被创建后先进queued等待调度。如果整个团队是平级并行所有 Agent 基本同时进入running。如果团队里有指挥官模式的 Agent那执行者们会有一批处于waiting等指挥官下发具体指令。running状态里有一个重要分支waiting可能是等外部工具返回可能是等另一个 Agent 的结果也可能是模型自己在思考。区分这三种等待很难从状态字面看出来我通常的做法是看它停在同一动作上的时长。如果同一动作停了超过两分钟没变化基本可以怀疑是卡住了或者陷入了反复试错。done也不完全等于干得好。Agent View 只告诉你流程上执行完了代码质量如何那是后面 Code Review 阶段的事。同理failed也不一定真失败了有时候只是单次工具调用报错Agent 会自己重试看它是否从failed跳回running就能判断。2.3 通过 Agent View 判断任务卡在哪一步这是读视图最有价值的地方。我总结了三类常见的卡点信号。第一类是高频重复模式。某个 Agent 的当前动作反复出现同一个命令比如五分钟内出现了十次npm test但它就是不进入下一步。这说明测试没过它在一个循环里打转。这种时候给它补充信息比让它继续跑更有效比如直接告诉它已经确认了第 43 行有个类型错误直接修那里。第二类是长时间无动作。状态是running当前动作却一直没变化停在某个文件编辑上。多半是模型进入长思考或者工具调用卡住。我会等一两分钟不行就中断重试。第三类是进度不均。两个 Agent 并行跑一个已经完成了 80%另一个才 10%。如果任务拆分真的合理不该差这么多。这时候我通常停掉慢的那个把它的活分一部分给快的那个。3. Agent Teams 的核心玩法定义、调度与协作看懂了视图下一步是解决一个更前置的问题这些 Agent 是怎么来的、怎么组队、怎么调度的。Agent Teams 的核心不是多开几个会话而是通过定义、分组、调度来获得可控的并行产出。3.1 定义 Agent用 Markdown 给 Agent 立人设Claude Code 里的 Agent 定义本质上是写在 Markdown 文件里的一组指令。我习惯把每个 Agent 的定义放在项目的.claude/agents/目录下一个文件对应一个角色。一个典型的定义文件长这样--- name: refactor-db description: 负责数据库访问层重构的专家 Agent tools: [Read, Edit, Grep, Glob, Bash] model: claude-sonnet-4-5 --- 你是一位资深 Python 后端工程师专注数据库访问层重构。 ## 职责范围 - 负责 app/db/ 目录下的全部代码重构 - 保持对外接口签名不变只改内部实现 - 重构完成后运行 pytest tests/test_db.py 验证 ## 工作守则 - 每次修改前先读完整目标文件不要只看片段 - 修改后必须运行测试测试不通过不提交 - 遇到接口变更需求时写入 docs/db-refactor-notes.md不要直接改动接口这里有几个容易被忽略的细节。description字段很重要它不光是注释在 Agent 调度的场景里它是别的 Agent 判断这个任务该交给谁的依据。描述写得越具体调度越精准不要写负责数据库相关要写清楚边界、工具、验收标准。tools字段控制这个 Agent 能用哪些工具。我的经验是给执行者只开最小工具集。比如审查类的 Agent 只给Read和Grep不给Edit防止它顺手改代码。重构类的 Agent 才给Edit和Bash。限定工具范围是减少越权乱搞最有效的手段。model字段可以根据任务复杂度配置。简单的格式化、翻译任务用轻量级模型就够复杂重构用性能更强的模型。混用模型能省不少成本这是多 Agent 天然的成本优势。3.2 组织 Agent Teams按职责分组还是按模块分组定义好 Agent 之后组队方式决定协作效率。我试过两种组织思路各有适用场景。按职责分组相当于建一个功能班子。比如代码审查员、测试工程师、重构工程师、文档维护者各管一行。这种组织适合工作流固定的场景先让审查员检查再让重构员动手再接测试员验证。好处是专精坏处是同一时刻可能只有一两个 Agent 有事干其他在waiting。按模块分组相当于各管一摊。比如订单模块、支付模块、用户模块每个模块配一个全能的 Agent负责改代码、跑测试、补文档。这种组织适合模块边界清晰的大仓库并行改造利用率高但要求模块之间真的没依赖。我现在的习惯是混用整体按模块拆每个模块团队里再塞一个轻量的代码审查 Agent专门盯本模块的质量。这样既拿到了按模块的并行效率又保留了按职责的专业分工。3.3 调度规则什么时候并行什么时候串行Agent 之间的协作不是无脑并行的我总结了一条简单的调度规则共享基础先串行独立任务再并行。比如一个项目里要先定 API 接口规范再让多个 Agent 分别实现不同的接口。接口规范就是共享基础这一步必须串行完成等规范文件落下去了后面的模块实现才能并行。如果连规范都没定就让各 Agent 开工出来的接口一定是各写各的合并时全是冲突。执行顺序上我惯用指挥官带兵模式。一个主 Agent 负责拆任务、派活、汇总其他 Agent 是被指派的执行者。指挥官不需要懂具体技术细节它的核心工作是判断任务边界、分配合适的 Agent、检查结果。在我们下一章的 Polter 实战里这个模式会体现得很完整。4. Polter 实战一个 4 人 Agent 团队并行重构的真实过程理论讲再多不如跑一遍。这一章用一个叫 Polter 的实际项目还原我从拆任务到合并代码的完整过程。Polter 是一个遗留多年的 Python 数据同步工具我接手的时候代码混乱、测试缺失、接口设计随意。我给它组了一个 4 人的 Agent 团队用并行模式完成了一次重构。4.1 Polter 项目背景一个很经典的烂摊子Polter 的场景很有代表性一个跑了三年的数据同步服务从最初的脚本一路长成了结构混乱的工程。我接手时它的问题清单大致如下数据访问层app/db/里所有表操作都写在几个大函数里SQL 到处都是API 层app/api/有十几个端点但参数校验靠手写 if-else错误处理不统一测试基本等于没有只有零星几个集成测试跑一次要连真实数据库日志系统混乱有的地方用 logging有的地方直接 print面对这种摊子如果用一个会话从头改到尾我估计光读完这些代码就要烧掉大量 token而且改到后面前面定的规范早忘了。所以我选择拆成 4 个并行任务。4.2 团队配置四个 Agent 的分工设计我给 Polter 配了四个 Agent分别对应上面四个问题模块。db-refactorAgent 负责重构app/db/目录目标是把 SQL 语句收拢到独立的 repository 类中对外保留原有函数签名。它需要Read、Edit、Grep、Glob、Bash工具因为要跑测试验证。api-rewriteAgent 负责重写app/api/的端点统一参数校验和错误处理格式。它同样需要编辑和运行测试的权限。test-harnessAgent 负责补齐单元测试把原来依赖真库的测试改成用模拟数据。它需要Read、Edit、Bash但我不给它改app/db/和app/api/之外文件的权限通过提示词里明确边界来约束。log-auditAgent 负责统一日志方案把零散的 print 全部换成结构化日志。这个任务最简单我给它配置的是轻量级模型用它跑这类体力活很划算。四个 Agent 之间没有直接调用关系它们通过 Git 分支隔离各自的工作区间。唯一的指挥官是主会话我作为人类给它们派活、看结果、处理冲突。4.3 执行过程复盘从启动到合并的完整链路整个执行过程我分成了五个阶段。第一阶段是我把四个任务写进一份任务书用明确的提示词发给主会话主会话根据 Agent 的文件定义把任务分派出去。分派时每个 Agent 都被要求先读各自负责目录的现状写一份简短的改造计划回传。第二阶段是并行执行。四个 Agent 同时在各自的目录里干活。我在 Agent View 里观察它们的进展重点盯三个信号每个 Agent 的文件修改数量是否合理增长、有没有停在某个操作上超过两分钟、token 消耗速率是否异常。第三阶段是局部验证。每个 Agent 完成修改后要在自己负责的范围内跑测试。这段期间 Agent View 里能看到大量Bash调用动作这是它们在执行测试命令。我允许它们在测试失败时自行修复两到三次但不允许它们跨目录改其他 Agent 的文件。第四阶段是合并。四个 Agent 各自工作在独立分支或独立提交上我把它们依次合并到主分支。这一步是实战里最容易翻车的地方下一小节单独讲。第五阶段是整体验收。合并完成后我的主会话统一跑全量测试和 lint确认四个模块合在一起没出问题。整个过程的耗时让我印象深刻单线程模式下我预计需要三到四个小时多 Agent 并行把实际耗时压到了四十分钟左右其中还包括了我反复观察和干预的时间。4.4 合并冲突处理多 Agent 并行最现实的一课合并阶段我如实说没有一次是顺滑的。Polter 这次遇到了一个非常经典的冲突。api-rewrite改了 API 层的错误处理格式把原来的返回任意错误字符串统一成了标准错误结构。而test-harness在写测试时恰好参考的是旧格式。当我把api-rewrite的分支合入主分支后test-harness的修改就跟它顶上了几十个测试用例断言全挂了。这个冲突不是文本冲突是逻辑冲突自动合并工具发现不了必须靠人判断谁先谁后。我的处理流程是先保留api-rewrite的新格式因为它是上游规范然后我让test-harness基于新格式重新生成测试断言。这次我故意用命令行的方式只让它工作不让它动代码逻辑因为测试断言理应跟随业务代码的格式走。这类问题的根源在于任务拆分时我忽略了 API 格式定义是一个共享基础。按第三小章的规则共享基础应该先串行定下来再并行。这是我这次实战里最深刻的教训任务拆得越狠越要先花时间把公共接口和规范钉死。5. 跑完多 Agent 后的避坑清单与提速心得多 Agent 模式跑顺了是真香但背后的坑也是真的多。这一章我把实战中踩过的坑、试出的方法、以及现在固定下来的一套经验写出来希望对你有直接的帮助。5.1 令牌消耗控制并行不等于让 Agent 随便跑多 Agent 并行最容易被低估的就是 token 成本。四个 Agent 同时跑token 是四倍速在烧的如果你让每个 Agent 都反复试错一个下午烧掉平时一周的量完全可能。我现在的控制手段有三个。一是在 Agent 定义里写死令牌预算和轮次上限比如每个文件最多修改 3 轮就跑测试、测试连续失败 2 次就停止并报告原因。限制不是为了让 Agent 偷懒而是逼它停下来等你做判断减少无意义的重复劳动。二是在派活时明确不必做的事比如不要顺手优化无关代码不要重构没有问题的函数。Agent 是有执行惯性的不给约束它会把小重构做成大规模改造token 也就在这种时候失控。三是混用模型。轻量型任务就给轻快模型跑只有核心重构、复杂 bug 定位才上性能强的模型。跑完 Polter 那次四分之三的 token 都花在db-refactor和api-rewrite上另外两个 Agent 的成本几乎可以忽略。5.2 日志与可观测性Agent View 之外的兜底手段Agent View 虽然直观但它只覆盖你在终端里看到的画面。多 Agent 跑起来之后我强烈建议在项目里提前加一层全量日志。具体做法是让每个 Agent 在执行过程中把关键决策点写入一个共享的docs/agent-log.md。比如决定用 repository 模式重构表访问测试断言从旧格式升级到新格式修改了数据库连接池配置。这份日志的价值不在于格式而在于它给了你一个事后复盘的时间轴。有一次两个 Agent 改过同一个配置文件的同一行Agent View 里根本看不出谁先谁后我只能靠日志里的时间戳去回溯是谁在几点钟动了那个配置。后来我把所有 Agent 必须写执行日志写进了 Agent 定义算是把这条踩坑经验固化成了流程。5.3 我跑多 Agent 前的固定三问现在每接到一个复杂任务我动手前都会先问自己三个问题。第一个问题任务的输出能不能被独立验证如果每个 Agent 的产出没有明确的验收方式那就别拆。这次没法验证拆了以后就只能靠猜靠猜的并行等于埋雷。第二个问题有哪些信息是多个 Agent 共用的把这些信息单独挑出来作为共享基础先处理让所有 Agent 都基于同一份事实工作。API 格式、数据模型、命名规范、错误码都属于这一类必须在并行开始前定稿。第三个问题最坏情况下哪个 Agent 会拖后腿一次并行只让瓶颈最少的三四个 Agent 去跑比一次开八个 Agent 然后互相等要快得多。Agent 数量不是越多越好数量一多调度和冲突处理的成本就会超过并行带来的收益。跑了几次多 Agent 之后我最大的感受是这玩意的难点从来不在怎么同时跑多个任务而在怎么让多个任务之间没有乱七八糟的耦合。Agent View 让你看得见它们Agent Teams 让你管得住它们但真正决定并行成败的还是你把人分块的能力。反正现在再遇到大项目我的第一反应已经不是让它一口气干完而是琢磨这件事到底能干干净净地切成几块。
阅读完成 · 觉得有帮助？
