DeepDojo.AI发布 2026-11-13更新 2026-11-13English
怎么给 Claude Code 子代理布置任务
功能准备上线前，我们总想把所有事情一次办齐：审查代码改动有没有业务回归，挖一挖鉴权漏洞，再把单元测试和性能基准测一遍。刚开始在一个主会话里顺着聊确实方便，聊着聊着就发现上下文被路由定义和测试日志塞满，光是排查一个冷门安全边界就来回拉扯了几十轮，主线任务停在了原地。
于是你把认证这块交给子代理（Subagent）：“帮忙看看认证。”过了一会儿，它交回一句“审查完成，未发现明显问题”。主代理还是不知道哪个调用会出问题，也没法判断这句话靠不靠得住。
委派本身不难，难在交出去的说明和收回来的结果都够用。常见的问题有：
- 委派说明太宽，子代理不知道看哪些文件、能不能改、交回什么；
- 交回的结果只有结论，没有位置、触发条件和代码依据，主代理没法核对；
- 链式交接时只传结论，前一个代理没验证的前提，在下一个代理那里悄悄变成了事实。
办法是在交出去之前写清五项：职责、输入范围、工具权限、输出格式，以及怎样交回主代理；交接时把已确认的事实和未确认的假设分开写；委派之前，再算一算协调成本抵不抵得过省下的上下文。
01 子代理是带着限制的专项调查员
子代理的角色，像主工程师临时委派出去的专项调查员。它带着被限制的工具权限，在独立的上下文中处理指定任务，完成后只把提炼好的结论和证据交回主会话。主代理始终负责整体方向，并核验各方回传的事实。
拿开头那句“帮忙看看认证”来说，可以改成：
读取 `src/auth/` 及对应测试，检查本次 diff 是否让未登录请求绕过鉴权。
只读，不改文件，不访问线上数据。需要其他模块时先说明原因。
每个发现给出位置、触发条件、代码依据和建议验证方法；区分已确认问题与待核实假设。
若缺少 diff 或无法确定比较基线，先报告缺口，不猜测。看完这份委派，再想想主代理会收到什么。如果只有一句“审查完成”，它仍不知道哪个调用会出问题。位置、触发条件和代码依据，才让它能回到文件核对，然后决定是否修复。
这里的限制也各有用处：只读让审查先停在发现阶段，禁止线上访问收紧数据范围，事实与假设分开，主代理才知道哪些结论已经确认。缺少 diff 时先报告，才能避免对着错误基线生成一份看似完整的报告。
02 先算协调成本，再决定委派
可以用下面的表判断：
| 场景 | 建议做法 |
|---|---|
| 一句固定提示词就能完成 | Slash Command |
| 需要固定流程、模板和参考资料 | Skill |
| 需要在工具调用前后自动检查 | Hook |
| 需要访问外部系统和实时数据 | MCP |
| 需要一个独立角色处理复杂子任务 | Subagent |
| 需要多个角色并行协作、互相汇报 | Agent Team |
按从简单到复杂的顺序选择：一句话能说清，用命令就够了；只是方法和模板固定，建个 Skill；想在某个系统动作前后加一道门禁，配个 Hook。
选择委派时，也要计算子代理的协调成本：
- 你得花精力把输入边界交代清楚。
- 子代理干完活，你还得复核它交回来的产物。
- 最后还要把各个角色的结论拼装在一起。
如果委派省下来的上下文空间，抵不过交接沟通耗费的力气，就留在主会话里直接做，效率反而更高。
长时间专项分析、不同工具权限、后台或可恢复工作、独立文件修改和多视角接续，都可能需要子代理。任务很短、主会话可直接完成、多个代理会重复劳动，或者只是想让模型“再想一次”时，留在主会话更直接。
03 定义文件：职责、触发和工具
子代理定义放在 Markdown 文件中，项目级在 .claude/agents/，用户级在 ~/.claude/agents/。文件由 YAML frontmatter 和 Markdown 系统提示组成：前者定义调用与权限，后者定义角色和工作方法。
---
name: code-reviewer
description: 审查代码质量、行为回归、测试缺口和安全风险。适用于用户要求 review、检查 diff、准备合并或评估近期改动的场景。
tools: Read, Grep, Glob
model: inherit
---
# Code Reviewer
## Role
你是代码审查代理，优先发现会导致错误行为、数据问题、安全风险或测试缺口的具体问题。
## Workflow
1. 确认变更范围。
2. 阅读相关代码和测试。
3. 优先寻找明确 bug 和行为回归。
4. 按严重程度排序。
5. 每条发现必须包含文件位置、原因、影响和建议修复方式。
## Output
- Findings
- Open questions
- Verification字段按需要添加：
| 需求 | 对应配置 |
|---|---|
| 名称、触发与最少工具 | name、description、tools |
| 移除能力、选模型、限执行 | disallowedTools、model、permissionMode、maxTurns |
| 加方法、外部服务或记忆 | skills、mcpServers、memory |
| 后台运行、隔离文件 | background、isolation |
同名定义按优先级覆盖。按 Claude Code 的子代理文档，从高到低依次是组织受管设置、CLI 的 --agents 临时定义、项目的 .claude/agents/、用户的 ~/.claude/agents/、插件自带的 agents/。排错时先确认实际加载的是哪一份定义。
description 要说明做什么、何时委派、到哪里结束，主代理靠它自动选择子代理。比如 code-reviewer 管行为和测试，secure-reviewer 管鉴权、注入与敏感数据。面对“看看改动有没有问题”，两者的描述都可能命中。这时回查职责边界：谁负责普通审查，何时转给安全角色，混合任务怎样交接？
用普通、安全专项和混合请求各试一次，再看实际覆盖。代理名出现在记录里，只说明它被调用了；是否读了该读的代码、留下可核对的发现，还得检查结果。除了自动委派，也可以显式点名，比如“请用 code-reviewer subagent 审查我最近的改动”，或者用 claude --agent code-reviewer 让整段会话以它为主代理。
04 工具权限从最小集合开始
工具权限决定子代理能做什么。先从完成任务所需的最小集合开始，再根据实际缺口补充：
| 写法 | 能做什么 | 适合 |
|---|---|---|
省略 tools | 可能继承较多能力 | 确实需要完整操作范围的实现任务 |
tools: Read, Grep, Glob | 只读取与搜索 | 安全审查、代码审查、架构分析、文档阅读 |
tools: Read, Write, Grep | 读取并写出文档 | 文档代理，是否需要 Bash 按实际工作决定 |
tools: Read, Edit, Bash, Grep, Glob | 运行和修复测试 | 测试代理，Bash 的范围要另外控制 |
看到最后一行，可以追问一次：留下 Bash 后，它实际还能做什么？tools 只决定工具是否可用，命令范围还要靠权限规则或 PreToolUse Hook 控制。去掉 Write 和 Edit，Bash 仍能写文件。即使只准备运行 npm test，也先看项目脚本做什么，再判断权限是否合适。
Claude Code 通常也提供内置角色，比如只读探索代码库的 Explore、在计划模式中研究方案的 Plan、处理复杂多步任务的 general-purpose。内置代理适合通用任务；任务包含稳定的项目规则、团队流程或固定输出时，再定义专用代理，让团队复用同一套边界。
05 链式交接：已确认、未确认、建议
多个代理可以依次协作：
First use the code-analyzer subagent to find performance issues,
then use the optimizer subagent to propose fixes,
then use the test-engineer subagent to design verification.链式协作要先定义交接格式。上一个代理输出结构化证据和结论，下一个代理才能稳定接续。一份最小交接格式长这样：
## 交接：性能问题分析
已确认事实：
- 热点函数 `renderList`，每次渲染重建全部 DOM 节点（profile 截图，`src/List.tsx:42`）
- 数据集 5000 条时渲染耗时 1.8s（基准脚本输出）
未确认假设：
- 虚拟滚动可能解决，但未测量列表高度是否固定
建议下一代理：
- 只针对 `renderList` 设计优化方案；不改动数据层（已排除数据获取瓶颈）optimizer 接手后，先核对这些依据的适用条件：
- 同版本、同输入的 profile 可以复用；条件变了，就重新测。
- 数据层已排除，且这次不在修改范围，继续守住这个边界。
- 虚拟滚动还只是一个建议，列表高度等前提尚待验证。
这样它能从已经查清的地方接着做，也知道哪里还不能下结论。若只交一句“用虚拟滚动优化”，下一代理很可能直接实现，前面的未验证条件就悄悄消失了。
长任务也可以先启动、之后再恢复同一个子代理，接着分析新的范围，适合大型分析、长期调研和多阶段排查。
06 审查、修复和验收分开
很多人喜欢配置一个“全能”的 super-reviewer：一边挑错一边修改，改完之后再自己审查自己的补丁，最后宣布“全部问题已修复”。
审查、修复和验收混在一起时，原始发现和改动对照更难核查。可以先留下只读报告，再按已有授权修复；可以拆成两个角色，也可以同一角色分两段做，关键是让最初的发现还能核对。修改后继续查实际结果，“全部修好”这句话本身不算证据。
常见角色可以按职责配置工具：
| 角色 | 职责 | 建议工具 | 输出要求 |
|---|---|---|---|
| Code Reviewer | 查 bug、行为回归、错误处理、边界条件和漏测 | Read, Grep, Glob | 位置、原因、影响、修复建议和验证方式 |
| Secure Reviewer | 只读检查权限、认证、输入校验、敏感信息与注入风险 | Read, Grep | 风险与证据，由主代理核实后安排修复 |
| Test Engineer | 分析漏测、设计策略、补测试、运行并解释失败 | Read, Write, Bash, Grep | 遵守项目现有测试框架 |
| Documentation Writer | 依据代码更新 API、功能文档和用户指南 | Read, Write, Grep | 明确文档类型、读者、结构和示例格式 |
| Implementation Agent | 实现功能、修改代码、补测试并运行验证 | Read, Write, Edit, Bash, Grep, Glob | 配合 worktree 隔离、独立文件所有权或确认点 |
| Debugger | 通过复现和日志缩小范围，提出修复并验证 | Read, Edit, Bash, Grep, Glob | 假设、证据、根因、修复和验证 |
| Data Scientist | 编写 SQL、分析数据、生成统计 | Bash, Read, Write | 优先只读权限，限制查询范围、行数和敏感字段 |
安全代理先以只读方式报告风险，若需执行测试或查询 diff，可让主代理提供结果，或另行开放受限命令。实现代理权限较高，并行时怎样隔离文件和资源，见让多个 Claude Code 子代理安全并行。
07 委派没带来改善时，先查拆分
每个代理都有自己的模型和工具调用。任务一多，先记录代理及父代理的名称、使用的工具、后台状态和结果是否被整合，留意任务是否无休止地继续。频繁委派却没有改善结果，就回查拆分：
| 现象 | 先查什么 |
|---|---|
| 发现经常被推翻 | 范围与判断标准 |
| 交接比做事还复杂 | 是否依赖太多主会话背景 |
| 汇总比直接完成更慢 | 协调成本是否抵消收益 |
如果你配置了一堆子代理，整体开发效率反而比单会话更慢、问题更多，先回头检查任务拆分是否合适。最典型的症状有两个：
- 给子代理写一份任务说明要花 20 分钟，比自己动手写代码还累。
- 子代理交回来的报告漏洞百出，主会话为了核实那些似是而非的推测，又得把源码重新通读一遍。
协调和交接的成本已经吃掉委派带来的收益时，就把那些依赖主线上下文的小任务收回主会话，保留一两个边界清楚、能够独立交付的子代理，例如只读安全审计或长流程文档生成。子代理少了，沟通链路变短，主工程师也才有精力核对关键的代码证据。多个子代理的结果最终怎样汇总，见 如实汇总 Claude Code 多代理的审查结果。
写完委派说明，站在主代理的位置读一遍：拿到它可能交回的结果，你能不能直接回到代码里核对？能，这份说明就够用了。