Claude Code 子智能体实战：让主线程保持干净
英文原题：Claude Code Subagents are Absolutely Insane。Web Dev Cody 用一个认证与安全审查的代码库示例，演示如何用多个 Claude Code subagents 并行做研究、审计和实现，同时避免主聊天上下文被大量文件与中间结论塞满。
一、问题引入：不是“能不能让 AI 找文件”，而是主线程能不能继续清醒
这个视频的出发点很具体：在 Claude Code 里问“这个项目哪里在做 authentication 或 authorization”，主线程当然可以自己去扫文件、读实现、整理摘要。问题是，这类探索会把大量路径、片段、候选判断和中间失败都塞进同一个上下文窗口。Cody 在演示里先让主线程独立找认证相关代码，然后继续要求它从安全角度审查这些文件。上下文占用从约 9% 增长到约 30%，而后续如果还要修复漏洞，主线程已经带着不少并非每个修复都需要的历史信息。
视频真正想讲的是一种工程化分工：把“探索”“审计”“实现”拆给不同的专用 subagent，让它们在各自独立的上下文里完成有限任务，最后只把压缩后的结论交回主线程。主线程不再承担所有浏览、比较和试错，它更像调度器和决策层。对于需要在大型代码库里反复定位、审查和修改的场景，这比单线程聊天更接近一个可管理的工作流。
核心判断可以转述为：如果一个子任务只需要局部上下文，就不要让它污染主线程；主线程越短，后续改代码的输出通常越稳定。
二、核心概念解释：subagent 是“独立上下文的专用工位”
Claude Code 的 subagent 不只是一个提示词模板。它更像一个带角色、模型选择、工具权限和独立上下文窗口的小型工作单元。视频里 Cody 通过 /agents 菜单创建个人 agent，让 Claude Code 先根据自然语言描述生成 agent prompt，再由用户选择可用工具、模型和颜色标识。这样做的实际收益，是把“该怎么搜、该怎么审、该怎么写”的行为约束提前固化，调用时只需要说明目标。
1. 文件查找 agent：快速、轻量、适合广撒网
第一个 agent 是 file finder。它的任务不是改代码，而是围绕一个研究目标找出相关文件，并返回简明路径列表。Cody 给它选择 Haiku，是因为这类任务追求速度和成本：它不需要深度设计能力，只需要能快速遍历、筛选、归纳。对大型项目来说，用多个 file finder 并发扫描不同区域，比让主线程串行读完所有候选文件更容易保持响应速度。
2. 安全审查 agent：用更强模型做判断
第二类 agent 用来审查潜在安全问题。它需要读文件、理解认证逻辑和返回可修复清单，因此 Cody 倾向选择 Opus 这类更强模型。这里的关键不是“越强越好”，而是任务匹配：文件定位可以快，安全判断要稳，修复实现要更注重代码质量。把这些职责分开后，每个 agent 的提示词和模型都能更贴近它要完成的事情。
3. 实现 agent：把修复任务拆成多个局部改动
视频里还创建了一个 clean code architect agent，用于实现安全修复，并强调可维护、可复用、DRY 和工程质量。Cody 的示例是让多个实现 agent 同时处理安全清单中的不同项。每个实现 agent 理论上只需要知道自己负责的漏洞和相关文件，而不必继承前面所有搜索与审计过程。这就是 subagent 在 coding 场景里的主要价值：并行不是唯一收益，局部化上下文才是更大的收益。
三、关键论点与实操步骤：从一个主线程任务拆成三段流水线
如果把视频里的演示抽象成可复用流程，它不是“多开几个 agent 让它们忙起来”，而是一条有顺序的流水线：先定位范围，再审查风险，最后分派修复。每一步的输出都应该足够短，足够结构化，能让下一步继续工作。
步骤一：先用主线程提出研究目标
示例目标是“列出项目里所有认证或授权相关位置”。这个目标适合拆给 file finder agent，因为它有明确边界：只返回文件和简短说明，不做安全判断，不改代码。一个好的目标描述应该包含范围、输出格式和禁止事项。例如“只要 concise list of files”，能减少 agent 把大段源码或推测塞回主线程的概率。
步骤二：并发启动多个查找 agent
Cody 让 Claude Code 启动五个 file finder agents。它们各自拥有独立上下文，可以同时遍历代码库。视频中他也提醒，更多 agent 往往能更彻底，但并非越多越好。合理做法是按代码库规模、任务风险和模型成本设一个上限。小项目两三个就够，大型 monorepo 可以按模块或边界分派。
步骤三：把查找结果交给审查 agent
拿到认证相关文件后，再让 security vulnerability scanner agents 审查这些文件，并返回可修复清单。这样审查 agent 不需要重新从整个项目开始找，它可以专注于已经定位出的范围。视频里 Cody 对比了主线程审查后的上下文增长：单线程方式到 30%，而多 agent 审查结束后主线程约 16%。这个数字不是普适基准，但说明了一个方向：主线程只接收总结，避免继承所有审查过程。
步骤四：再把修复清单交给实现 agent
最后，clean code architect agents 可以针对不同漏洞并行实现。这里要注意权限和冲突：如果多个 agent 同时改同一文件，合并成本会升高；如果每个任务都能限定到独立文件或独立模块，并行收益会更明显。实践中可以先让 agent 产出修复计划，再由主线程决定哪些可以并行执行，哪些必须串行。
四、对比表格：什么时候用主线程，什么时候派 subagent
| 任务类型 | 更适合的执行方式 | 优点 | 主要风险 | 决策建议 |
|---|---|---|---|---|
| 快速问答、少量文件解释 | 主线程 | 交互成本低，反馈快，不需要额外调度 | 如果问题扩展成多文件探索，上下文会快速变胖 | 保持在主线程内完成，超过 3-5 个文件后再考虑拆分 |
| 代码库范围定位，例如查认证、支付、缓存入口 | 多个 file finder subagents | 并发覆盖多个区域，主线程只拿压缩后的路径清单 | agent 之间可能重复搜索，结果需要去重和合并 | 给出明确输出格式：文件路径、理由、置信度，不要源码长摘录 |
| 安全审查、架构风险审查 | 审查型 subagent，通常用更强模型 | 独立上下文能承载更深入推理，主线程少背中间过程 | 可能给出误报或忽略业务约束 | 要求输出“证据 + 风险 + 修复建议”，最后由主线程复核 |
| 多个独立修复项 | 实现型 subagents 分派 | 并行处理，局部上下文更干净，每个 agent 只看相关文件 | 同文件冲突、风格不一致、测试遗漏 | 先按文件边界拆任务，提交前统一 diff、测试和代码审查 |
| 跨模块大重构 | 主线程规划 + 少量 subagent 调研 | 保持统一设计判断，同时利用 subagent 补充事实 | 如果过早并行实现，容易出现不兼容方案 | 先用 subagent 做影响面分析，不急着让它们直接改代码 |
五、引用块：视频里最值得记住的一句话
“这些 agents 使用的是完全独立的上下文窗口，所以它们做的事情不会影响主线程。”
这句话是整段演示的中心。很多人理解多 agent 时只盯着“并发更快”，但在 coding agent 场景里，速度只是表层收益。更重要的是上下文隔离：探索文件时产生的大量噪声，不需要跟着进入安全修复；安全审查时的所有候选推理，也不需要污染最终实现。主线程只保留被压缩过的事实、决策和待办项，后续让模型改代码时，它面对的是更小、更相关的输入。
这也解释了为什么 Cody 会反复提到 context window。上下文不是越大越好。长上下文能容纳更多材料，但模型对开头和结尾的信息往往更敏感，中间信息容易被弱化。把所有东西都塞进主线程，看似信息充分，实际可能让最重要的修复目标被大量探索痕迹淹没。
六、时间戳目录
七、落地建议：给工程团队的一套用法
把这个视频用在真实团队里，建议先从“只读 subagent”开始。也就是先创建 file finder、risk reviewer、test mapper 这类只研究不改代码的 agent。它们的输出格式固定为短清单，主线程负责判断是否进入实现阶段。这样即使 agent 漏掉一部分内容，也不会直接制造代码风险。
第二步再引入实现型 agent。实现型 agent 应该被约束在非常具体的目标上，例如“只修改登录 token 过期校验”“只补某个 API route 的权限检查”“只为某个 service 增加单元测试”。不要让十个实现 agent 同时对同一批文件自由发挥。并行越强，越需要边界、验收和冲突处理。
第三步是建立固定验收流程：主线程在每轮 agent 输出后都要检查 diff、运行测试、确认没有无关修改。视频展示的是能力入口，不是完整软件交付流程。真正可复用的模式应该是：subagent 搜集事实，主线程做决策；subagent 执行局部任务，主线程做集成；subagent 提供候选修复，主线程用测试和 review 收口。
八、相关推荐
如果你想把这节课放进更完整的 Agent 工程路线里，可以继续看下面几篇课程页：