用 Claude Code 原生子智能体把大任务派给专家：.claude/agents/ + Task 工具并行派发

Claude Code 的 Task 工具能在一次会话里拉起一个「子智能体」：它拥有独立的上下文窗口、可单独配置的工具白名单，干完活把结构化结果回传给父 Agent。配合 .claude/agents/ 目录里的 Markdown 专家定义，以及 CLAUDE.md 里的自动派发规则，你可以把「探索代码库 / 写测试 / 做安全审查」这类重复性专家活儿自动分派出去，父 Agent 只做协调。本教程手把手写三个专家子智能体，并演示并行派发与只读权限边界。

🧩 本教程适合：每天都在用 Claude Code 做开发、想把大型任务拆给专家并行处理、又不想每次手动写派发提示词的开发者。需要本地装好 Claude Code 并能跑 Task 工具。

Step 1：理解子智能体：隔离的上下文与工具白名单

1 它和「同一个会话」有什么不同

子智能体不是父 Agent 的一段长上下文，而是一个独立进程：它看不到父 Agent 的历史对话（除非你明确要求），只能用它被分配的工具，干完返回你指定的产物（摘要、报告、文件内容）。这让专家活儿互不干扰，也避免把整个代码库塞进每个子智能体的窗口。

父 Agent（协调者）
 ├─ 子智能体 A：只读探索代码库  → 返回架构地图
 ├─ 子智能体 B：写 Jest 测试     → 返回测试文件
 └─ 子智能体 C：安全审查        → 返回风险清单

💡 适用信号：当一个活儿「范围清晰、能并行、产物可描述」时，就适合派给子智能体。模糊的「帮我看看整个项目」更适合留在主会话。

Step 2：写第一个专家子智能体

2 .claude/agents/code-reviewer.md

在仓库的 .claude/agents/ 下放一个 Markdown 文件，YAML frontmatter 决定它的名字、触发描述和工具权限，正文是它的系统提示。

---
name: code-reviewer
description: 审查近期代码改动中的缺陷、安全与风格问题，提交前或开 PR 前主动使用
tools: Read, Grep, Glob, Bash
---
你是一名代码审查员，任务是找 bug 而不是写代码。被调用时：
1. 运行 git diff HEAD~1 看最近一次改动
2. 检查：硬编码密钥、SQL 注入、空值处理、缺失错误分支
3. 返回带 CRITICAL/HIGH/MEDIUM/LOW 分级的 Markdown 报告，附 file:line
不要修改任何文件，只读。

权限边界：tools 白名单是子智能体的安全闸门。审查类子智能体只给 Read/Grep/Glob/Bash（只读命令），绝不给 Write/Edit，防止它「顺手」改了代码。写测试的子智能体才需要 Write/Edit。

Step 3：用 Task 工具手动并行派发

3 一次发多个，让它们同时跑

在 Claude Code 会话里，用 Task 工具起子智能体。多个独立的 Task 调用放在同一轮，Claude Code 会并发执行，回来再汇总。

# 自然语言派发（在 Claude Code 里直接说）
"并行启动三个子智能体：
 1. 探索 API 端点并总结用途
 2. 梳理数据库 schema 与关系
 3. 画出认证流程
各自返回摘要，不要返回完整文件内容"

🔑 派发提示词要写清三件事：工作范围（只做哪部分）、是否可并行、要返回什么格式。范围越明确，子智能体产出越稳。

Step 4：用 CLAUDE.md 让派发自动化

4 匹配到审查请求就自动走只读子智能体

把派发策略写进 CLAUDE.md，Claude Code 每次会话开头都会读它，于是「只要有人要求审查代码」就自动套用你定义的模式，不用每次口述。

# 代码审查规范
当被要求审查代码时，始终使用一个只读子智能体（Glob/Grep/Read 权限）。
审查必须覆盖：安全漏洞、性能问题、是否违反 /docs/architecture.md 的项目约定。
结果以带 file:line 的优先级清单返回。

触发质量：子智能体的 description 字段是 Claude Code 决定「何时派发」的依据。写具体触发条件（「提交前或开 PR 前」）比写能力（「安全专家」）命中率高得多。

Step 5：给子智能体限权与选型

5 工具白名单 + 便宜模型

子智能体可以单独指定 model，专家活儿用更便宜的模型（如 sonnet 档）往往够用，省钱又不影响主链路质量。

---
name: test-runner
description: 为给定组件编写并运行单元测试
tools: Read, Write, Edit, Bash
model: sonnet
---
你是测试编写者。输入组件代码，输出 Jest 测试文件，
并运行 npm test 确认通过再返回。

💡 状态隔离是子智能体的默认行为：每个子智能体调用无状态，不会在任务中途互相通信。需要跨子智能体共享结论时，让父 Agent 在汇总后统一注入。

Step 6：常见坑与红线

6 避开上下文污染与越权

实践里最容易踩的坑：把整个代码库塞给每个子智能体（浪费窗口且互相干扰）、给审查子智能体开放 Write（它本该只读）、派发提示词太模糊导致产出不可用。

# 反例：范围不清，子智能体无从下手
"帮我看看这个项目"

# 正例：范围、输入、产物都明确
"用 Explore 子智能体（very thorough）梳理 src/server/routes/ 下的
所有 API 端点，返回端点清单与各自职责，不超过 400 字"

红线：任何会改动文件、提交代码、访问凭据的子智能体，tools 都要严格收敛；涉及 auth、支付、用户数据的审查，强制走只读子智能体，再人工合并结论。

常见问题速查

现象	原因与处理
子智能体不被自动派发	检查 .claude/agents/ 文件是否在项目根，description 是否写了具体触发条件
子智能体改了不该改的文件	收紧 tools 白名单，只读类只给 Read/Grep/Glob/Bash
并行后结果对不齐	在父 Agent 提示里要求「各自返回结构化摘要」，由你统一汇总

← 返回教程中心