ClaudeCode 工程化学习 · 子代理篇Sub-Agents 核心概念与应用价值跑完测试 → 500 行日志搜一遍代码 → 200 行 grep分析错误 → 一堆中间推理——这些执行过程对当下必要对后续决策全是噪声。让 Claude 记得更少、但记得对。一句话开场如果让一个人同时干调研、写代码、跑测试、写文档最后他脑子里塞满细节已经记不清最初的目标是什么了。但如果给一个团队每人负责一件事做完只回一份结论——决策者拿到的是干净的报告执行过程永远不会污染主对话。子代理Sub-Agents就是给 Claude 配的那个团队。为什么需要 Sub-Agents上下文污染问题什么是上下文污染我们先看一个典型场景让 Claude 跑一遍测试。跑测试 → 500 行日志 搜代码 → 200 行 grep 分析错误 → 一堆中间推理过程这些内容有两个共同特征维度表现对执行过程必要——少了它们 Claude 无法判断对错对后续决策噪声——主对话并不需要这些细节持续时间默认不会过期永久占用上下文窗口根因在于Claude Code 不会自动过期临时数据它默认把这些临时的过程数据存储为了长期决策记忆。污染的具体后果接近上限未到上限用户提问主对话开始测试 500 行搜索 200 行错误分析 300 行上下文窗口膨胀还剩多少后续任务注意力下降但是混淆执行噪声越堆越多主对话真正关心的结论反而被淹没。这就是上下文污染。核心概念主代理与子代理什么是主代理主代理就是当前的主对话本身。它继承了 CLAUDE.md 的全部记忆、当前任务上下文、以及所有主对话级别的工具权限。什么是子代理子代理是一个有独立规则、工具权限、上下文窗口、为完成某一类任务的专职助手。类比职场一个岗位做一件事并且有明确的权限边界。上下文隔离机制委派任务只回结论子代理 独立上下文窗口专项任务执行过程结论主代理 主对话上下文用户提问主决策关键特性子代理天然拥有独立的上下文窗口执行完即丢弃只把结论带回来。这是 Claude Code 里唯一一个结构上允许执行完即丢弃的组件。四句话概括子代理的核心不是为了 Claude 做得更多而是为了 Claude 记得更少但记得对执行过程不再污染主对话用与不用的本质区别方式一事必躬亲亲自调研市场输出 200 行分析、亲自写代码输出 500 行日志、亲自测试又是 300 行、亲自写文档……最后主对话里塞满了各种细节已经记不清最初的目标是什么了。方式二专人专岗安排一个市场专员去调研只需要他给你一份 1 页的报告安排一个测试工程师去跑测试只需要他告诉你结果是通过还是有 3 个失败安排一个技术文档专员去写文档……每个人带着明确的任务出去完成后只把结论带回来。对照表维度事必躬亲不用子代理专人专岗用子代理主对话承载内容全量执行过程仅结论上下文窗口快速膨胀保持清洁注意力分配被过程分散专注决策并行能力串行多任务并行子代理的四大工程价值价值一隔离——解决上下文污染通过独立的上下文窗口把对当前执行有用但对后续决策毫无价值的日志、搜索结果、中间推理挡在主对话之外。子代理执行完即丢弃只把结论带回来。反例在主对话里直接pnpm test500 行日志直接进上下文。正例派test-runner子代理去跑回报3 个失败在 src/auth/login.test.ts。价值二约束——把行为边界变成系统规则通过工具权限边界把我希望你别这么做变成你物理上做不到。代码审查只能读、修 bug 才能写——角色职责不再依赖提示词自觉。反例主对话里加一段提示词请不要修改 migrations 目录Claude 大概率会忘掉。正例在子代理的 frontmatter 中只配置tools: Read, Grep, Glob物理上就不能写文件。价值三复用——把经验沉淀为版本化资产当子代理被定义成文件、放进版本控制后好的使用方式就从一次性对话变成了可共享、可迭代的工程资产。反例每次都口头描述帮我跑一下测试表述每次都略有不同。正例.claude/agents/test-runner.md文件在团队仓库共享新人 clone 仓库后立刻可用。价值四并行——天然的多任务加速器子代理可以后台运行让原本串行的复杂任务同时推进。反例依次在主对话里调研认证逻辑、数据库设计、API 接口每个调研都挤占主上下文。正例同时派 3 个子代理并行调研最后主对话只拿到 3 份结论报告。这四点合在一起标志着 Claude Code 的使用方式从对话技巧正式跨入工程系统。什么时候该用子代理子代理的价值不在于能不能用而在于该不该用。判断的简单标准主对话到底需不需要承载执行过程本身。适合用子代理的四类任务第一类高噪声输出的任务执行过程中会产生大量中间信息但主对话真正关心的往往只有一个结论。跑测试套件数千行输出 → “3 失败”检索大代码库成百上千 grep 结果 → 路径列表分析错误日志一堆中间推理 → 根因 修复建议第二类角色边界必须明确的任务有些事情你只希望 Claude看而不希望它动手有些操作只能在特定目录、特定范围内发生。代码审查只能读数据库只读分析Read-Only 工具敏感文件分析不能写第三类可以并行展开的研究型任务当探索之间相互独立时与其串行调研不如并行派子代理。同时调研认证、数据库、API 三个模块对比多种技术方案从多个视角分析同一个问题第四类可拆成清晰阶段的流水线式任务每个阶段的目标、权限、输出都明确时用子代理固定责任。定位代码 → 代码审查 → 修改 → 测试验证不适合用子代理的场景需要频繁来回讨论和即时调整的对话主对话需要看到完整执行过程才能决策的情况任务本身很轻启动子代理反而增加开销一条关键约束子代理不能嵌套子代理这是架构硬约束所有编排必须由主对话完成。调度调度❌ 不允许主对话子代理 A子代理 B这意味着如果你需要先审查再修复必须由主对话依次调用两个子代理而不是让第一个子代理去调用第二个。流水线的调度中心只有一个就是主对话本身。如果需要在子代理内复用知识用skills字段预加载而非再嵌套一个子代理。配置详解子代理的 frontmatter子代理使用 Markdown YAML frontmatter 格式---name:代理名称description:何时被调用tools:工具列表disallowedTools:禁止工具列表model:sonnet|opus|haikupermissionMode:default|acceptEdits|bypassPermissions|planskills:预加载的 skill 列表hooks:子代理专属生命周期 Hook---正文 子代理的系统提示词子代理只会收到这段系统提示词和基本环境信息工作目录等不会继承主对话的完整系统提示词。description 的设计艺术description字段决定了 Claude 何时自动调用你的子代理——这是配置中最重要的设计决策。---name:code-reviewerdescription:Review code for quality,security,and best practices. Use proactively after code modifications.tools:Read,Grep,Glob,Bash---要点说明做什么审查代码质量、安全、规范说明什么时候用代码修改后或用户请求时Proactively关键词会鼓励 Claude 在合适的时机主动委派任务tools vs disallowedTools白名单与黑名单表达方式适用场景tools: [Read, Grep]子代理只需要少数工具白名单更清晰disallowedTools: [Edit, Write]子代理需要大部分工具但排除个别黑名单更简洁不要同时使用两者——选一种即可。工具权限应遵循最小权限原则能用 Read 完成的任务就不要给 Edit。常见子代理的工具组合推荐子代理类型推荐 tools代码审查Read, Grep, Glob测试运行器Bash配合 hooks 限制命令数据库只读Bash配validate-readonly-query.sh校验影响分析Read, Grep, Glob, Bash文档撰写Read, Write, Globmodel模型选择与默认值model字段决定子代理使用哪个模型。可选sonnet/opus/haiku留空则继承主对话模型。权衡原则复杂推理任务架构分析、复杂 Bug 定位→ opus常规任务代码审查、测试运行→ sonnet简单批量任务文件查找、格式校验→ haikupermissionMode权限模式控制子代理在执行过程中遇到需要权限的操作时如何处理模式行为default每次需要权限都询问acceptEdits自动接受文件编辑bypassPermissions跳过所有权限检查plan先规划再执行Plan 子代理默认子代理会继承主对话的权限上下文但可以通过此字段覆盖。skills为子代理预加载知识---name:impact-analyzerdescription:Analyze impact scope of code changes on the full call chain.tools:Read,Grep,Glob,Bashskills:-chain-knowledge# 链路拓扑和 SLA 约束-recent-incidents# 近期事故记录---这是子代理内复用知识的正确做法——通过skills字段预加载而不是嵌套另一个子代理。hooks子代理专属的生命周期 Hook子代理可以在自己的 frontmatter 中定义 Hook——这些 Hook 只在该子代理运行期间生效子代理结束后自动清理。---name:db-readerdescription:Execute read-only database queries.tools:Bashhooks:PreToolUse:-matcher:Bashhooks:-type:commandcommand:./scripts/validate-readonly-query.sh---典型用法PreToolUse 校验命令是否安全PostToolUse 记录执行日志子代理结束时清理临时文件子代理的存放位置与优先级位置路径适用场景项目级仅当前项目可用./.claude/agents/项目特有的角色比如针对特定框架的测试运行器用户级所有项目可用~/.claude/agents/通用角色比如日志分析器、通用代码审查器优先级项目级覆盖用户级同名时项目级优先生效。创建子代理的三种方式方式一交互式创建在 Claude Code 中输入/agents按照向导操作输入/agents选择 “Create new agent”选择存放位置User-level 或 Project-level选择 “Generate with Claude” 并描述功能选择需要的工具选择模型保存方式二手写配置文件直接创建.claude/agents/your-agent.md文件。优势是更精细的控制方便版本管理可以从其他项目复制。方式三CLI 参数临时创建通过--agents参数可以在启动 Claude Code 时传入 JSON 格式的子代理定义。这种方式创建的子代理仅在当前会话中存在不会保存到磁盘。特别适合 CI/CD 自动化时在流水线中临时创建任务专用的子代理claude--agents{test-runner: {description: Run tests, tools: [Bash]}}实战一个最小可用的子代理配置---name:code-reviewerdescription:Review code for quality,security,and style issues. Use proactively after any code modification.tools:Read,Grep,Globmodel:sonnetpermissionMode:default---You are a senior code reviewer. When reviewing code:1. Check for security issues (hardcoded secrets,SQL injection,XSS) 2. Check for style consistency with the codebase 3. Check for missing tests 4. Provide a structured report with severity levels (blocker / major / minor / nit) Do NOT modify code. Only report findings.配置要点解读description中明确after any code modification配合 “Use proactively” 鼓励自动触发tools只给只读工具物理上不能修改代码约束价值permissionMode: default让敏感操作保持询问系统提示词明确职责与边界不给它越权空间常见陷阱速查错误做法后果正确做法description 写得太泛子代理从不触发或触发时机不准明确做什么 什么时候用用 “Proactively” 关键词tools 和 disallowedTools 同时用配置冲突报错二选一想让子代理再调用子代理架构不支持主对话必须亲自调度用skills字段预加载复用知识用子代理跑小任务启动开销 收益小任务直接主对话处理子代理配置里给太多工具违反最小权限原则行为不可控只给完成任务必需的最小工具集项目级和用户级同名子代理行为不一致调试困难用命名空间区分或明确选用哪一层期望子代理继承主对话系统提示词实际只继承工作目录和环境信息把核心指令写在子代理自己的 frontmatter 与正文中把子代理当 Skill 用子代理有独立上下文启动开销大静态规则用 Skill动态隔离任务用 Sub-Agent局限性声明子代理不是万能药几个边界必须诚实指出不能嵌套架构硬约束复杂流水线必须由主对话统一调度启动开销每个子代理启动都有固定 token 成本简单任务直接交给主对话更划算模型限制子代理与主对话使用同一权限上下文敏感操作仍需主对话授权调试成本子代理的执行过程对主对话不可见问题排查需要看子代理的返回结果反推CI/CD 临时场景临时子代理CLI 方式只在当前会话存在复杂流水线需要持久化定义并行数量同时派 N 个子代理意味着 N 倍的 token 消耗需权衡收益与成本核心要点回顾子代理的核心是隔离通过独立的上下文窗口把执行噪声挡在主对话之外只回结论四大工程价值隔离、约束、复用、并行对应内存管理、安全边界、组织效率三大经典软件工程命题四类适用任务高噪声输出 / 角色边界明确 / 可并行研究 / 流水线式阶段任务架构硬约束子代理不能嵌套子代理所有编排由主对话完成配置核心字段description决定何时触发tools最小权限原则model性能/成本权衡存放优先级项目级覆盖用户级子代理把对话技巧升级为工程系统——这是 Claude Code 从 ChatGPT 进化为团队编排平台的关键组件。延伸阅读Claude Code 官方文档 - Sub-AgentsClaude Code Frontmatter 规范Agent SDK 编程接口