1. 引言

Claude Code 在 “单个对话里完成一切” 当然可以，但当任务变复杂时，你会遇到三个典型瓶颈：

• 上下文污染：你让它又写业务、又跑测试、又审安全、又写文档，对话会越来越“杂”，质量波动大。
• 角色混乱：同一个模型既当开发又当审查，很容易出现“自己给自己过”的情况。
• 可复用性差：团队里每个人都在重复写“你是测试专家/你是安全审计专家”的提示词。

Subagents 的定位就是：把这些 “固定角色” 固化成可复用配置，让主对话负责编排，子代理负责专业产出。

2. Subagents 是什么？

Subagents（子代理）是预配置的 AI 人格，每个 Subagent 都有：

• 独立的指令与风格：可以理解为一个长期雇佣的 “测试工程师/安全审计/文档工程师”
• 相对隔离的上下文：减少对主对话的污染，让主对话保持 “编排者” 角色
• 独立的工具权限：比如只允许 Read/Grep，禁止 Bash/Write）

可以把主 Claude 理解成 Tech Lead / Orchestrator：拆任务、分派子代理、汇总结果、把子代理当成 “专职工种”。

3. Subagents 配置

Subagents 本质上就是一组 Markdown 文件，按作用域放两种位置：

用户级（跨项目复用）：

• 目录：~/.claude/agents/
• 适合：你个人常用的通用角色（比如安全审计、代码审查、文档写作）

---

项目级（推荐团队共享）：

• 目录：{project}/.claude/agents/
• 适合：和项目强绑定的角色（比如“本项目测试工程师：约定 Jest + 特定目录结构”）

团队最佳实践：把项目级 Agents 版本化提交到 Git，让新同学克隆仓库即可拥有同一套“AI 工种”。

---

如果把 Subagents、Hooks、Commands 都落到项目里，结构通常长这样：

your-project/
├── .claude/
│   ├── settings.json
│   ├── agents/
│   │   ├── test-writer.md
│   │   ├── code-reviewer.md
│   │   └── security-auditor.md
│   ├── hooks/
│   │   ├── format.sh
│   │   ├── auto-test.sh
│   │   └── guard-bash.sh
│   └── commands/
│       ├── review.md
│       └── test.md
└── CLAUDE.md

---

3.1 配置格式

Subagent 文件是 “带 YAML Frontmatter 的 Markdown”，结构非常固定，例如：

---
name: test-writer
description: 专门编写单元测试和集成测试的 AI 助手
tools: Read, Write, Bash, Grep
model: sonnet
permissionMode: inherit
skills: api-testing
---

# Test Writer Agent

你是一位测试专家，专注于编写高质量的测试代码。
...

可以把它理解为：

• YAML 区：机器可读（名字、权限、模型、技能）
• 正文：人类可读（角色定义、工作流程、输出格式、约束条件）

3.2 核心配置

下面是最常用也最影响效果的四组字段。

3.2.1 tools（让子代理“能做什么”）

tools 是最直观的安全边界与能力边界：

• Read/Grep：读代码、搜代码（适合审查类）
• Write/Edit：写代码、改代码（适合实现类）
• Bash：跑命令（适合测试/构建/脚手架类）

建议：能不开放就不开放。比如“安全审计”大多数时候只需要 Read, Grep。

3.2.2 permissionMode（让子代理“默认怎么申请权限”）

常见模式：

• inherit：继承主会话的权限策略（最常用、最稳）
• allow-all / deny-all / ask-all：按字面意思理解

建议：团队场景以 inherit 为主；确实需要强约束时再用 deny-all（例如“纯审查只读”）。

3.2.3 model（让子代理“用哪个模型”）

如果你的团队对成本/速度/质量有分层策略，可以这样用：

• 主对话用更强模型负责编排与关键决策
• 子代理按角色选择模型：例如测试/文档用更快模型，安全审计用更强模型

具体模型名建议用你在 settings 里配置的别名（便于后续统一切换）。

3.2.4 skills（把可复用步骤注入到子代理）

Skills 更像“标准作业程序（SOP）模板”，Subagent 更像“岗位说明书”：

• Skill：如何做（步骤/命令/输出结构）
• Subagent：谁来做（角色、边界、口吻、工具权限）

把 Skill 挂到 Subagent 上，能让团队把重复流程 “标准化”：例如 api-testing、db-migration、release-checklist。

---

4. Subagents用法

交互式的用法如下，输入以下命令：

/agents

通过这个命令，可以：

• 创建新 Agent
• 选择某个 Agent 执行任务
• 查看正在运行/已完成的 Agent 状态

当然也可以通过CLI 直接指定：

claude --agents test-writer "为 src/api/user.js 编写测试"

也可以用 JSON 临时定义一个轻量代理（适合临时任务）：

claude --agents '{"name":"reviewer","tools":["Read","Grep"]}' "审查 src/ 下的潜在安全问题"

当多个 Agent 并行干活时，可以理解/agents 就是 “任务面板”，把 “后台任务” 变得可见，也可以通过如下方式判断是否适合使用Subagent：

• 适合 Subagent：审查/测试/文档/重构这类“有固定输出结构、可重复执行”的工种
• 适合 Subagent：你希望它有严格边界（只读/禁 Bash/固定输出格式）
• 不适合 Subagent：你还在探索需求、频繁变更方向（主对话更灵活）
• 不适合 Subagent：一次性小任务（新建文件改两行），直接主对话更快

6. 最佳实践

6.1 实践原则

让子代理“可控、可复用、可验收”

---

① 子代理的提示不要写成“百科全书”

• Subagent 的正文更像岗位说明书：只放长期有效的原则、约束、输出格式；项目细节放到 CLAUDE.md 或 Skill 里。

---

② 给每个 Agent 定一个“硬输出格式”

没有格式，主对话就很难汇总；一旦输出结构固定，主对话就能做到：

• 并行启动多个 Agent
• 把结果汇总成统一报告
• 快速定位“必须修”的条目

---

③ 用工具权限做“最小能力原则”

• 审查类：尽量只读（Read/Grep）
• 写代码类：再开放 Write/Edit
• 跑命令类：再开放 Bash（并配合 Hooks 做危险命令拦截）

---

④ 让主对话负责编排，子代理负责产出

推荐的协作方式：

1. 主对话拆解任务与验收标准
2. 子代理按角色产出（测试/审查/文档）
3. 主对话统一验收与合并决策

这样做的好处是：责任边界清晰，质量更稳定。

6.2 Subagents、Hooks、Skills 组合工作

Subagents 解决的是“角色复用与并行”，Hooks 解决的是“自动触发与门禁”，Skills 解决的是“步骤模板”。

一个团队常见的组合拳是：

1. Subagent：test-writer 负责补齐测试
2. Hook：PostToolUse 自动格式化/跑测试（不阻断）
3. Hook：Stop 做最终质量门禁（测试是否通过、lint 是否干净、git status 是否干净）
4. Subagent：code-reviewer 只读审查给出必须修清单

6.3 案例模板

6.3.1 security-auditor（只读安全审计）

---
name: security-auditor
description: 安全审计与合规检查（只读）
tools: Read, Grep
permissionMode: deny-all
---

# Security Auditor

目标：找出高风险漏洞与可利用路径，并给出可执行修复建议。

输出格式（必须遵守）：
1) Critical（必须立刻修）
2) High（优先修）
3) Medium（建议修）
每条包含：文件路径 + 风险说明 + 复现/攻击思路 + 修复建议

6.3.2 test-writer（写测试 + 跑测试）

---
name: test-writer
description: 为变更补齐单测/集成测试，并尽量跑一遍验证
tools: Read, Write, Edit, Grep, Bash
permissionMode: inherit
---

# Test Writer

规则：
- 只改测试相关文件，避免改业务逻辑（除非确实需要测试注入点）
- 测试命名清晰，覆盖主路径 + 关键异常路径

输出格式：
- 新增/修改了哪些测试文件
- 运行了哪些测试命令（若无法运行，说明原因与替代建议）

6.3.3 code-reviewer（代码审查官）

---
name: code-reviewer
description: 严格代码审查（只读），给出可执行的 review checklist
tools: Read, Grep
permissionMode: deny-all
---

# Code Reviewer

重点检查：
- 逻辑正确性（边界/异常/并发）
- 可维护性（命名/结构/重复）
- 性能（热路径/无谓 IO/复杂度）
- 安全（注入/鉴权/敏感信息）

输出格式：
1) 必须修复（带原因与建议）
2) 建议优化
3) 可选风格

6.3.4 refactor-engineer（重构工程师）

---
name: refactor-engineer
description: 面向可维护性的重构（小步、可验证）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---

# Refactor Engineer

原则：
- 每次重构只解决一个主题（例如“拆分函数”“去重复”“收敛边界”）
- 先加测试/保持行为等价，再动结构

输出格式：
- 重构目标与范围
- 关键改动点（按文件列出）
- 风险点与回滚策略

6.3.5 doc-writer（文档工程师）

---
name: doc-writer
description: 为功能/模块补齐开发者文档（README/ADR/使用示例）
tools: Read, Write, Edit, Grep
permissionMode: inherit
---

# Doc Writer

要求：
- 用最短路径让新同学跑起来：安装 → 配置 → 运行 → 常见错误
- 每个关键命令给出示例

输出格式：
- 新增/修改了哪些文档文件
- 文档中新增了哪些“可复制命令”

---

7. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Subagents 的设计理念与工程价值：它并不是“多开几个对话”的技巧，而是一套 角色固化、上下文隔离、权限可控的协作机制。通过将测试、审查、安全、文档等稳定工种抽象为 Subagent，并与主对话形成“编排者 + 专职角色”的协作模式，可以显著降低上下文污染与角色混乱，让复杂任务具备可并行、可复用、可验收的工程属性。

希望本文能对大家深入理解和落地使用 Claude Code Subagents 有所帮助，也欢迎在评论区分享你的 Agent 设计、团队实践与踩坑经验。感谢阅读，本文完！