Column 1
Column 2
1. Subagents 定义和用处
什么是 Subagents
Subagents 是配置在项目
.claude/ 目录下的专用 AI 代理。每个 Subagent 具有独立的：- 身份定义：专注于特定领域的专家角色
- 工具权限：精确控制可访问的工具集
- 行为指令：定制化的系统提示词
核心价值
价值维度 | 说明 |
职责分离 | 将复杂任务分解为多个专业角色，各司其职 |
专业深度 | 每个 Subagent 聚焦单一领域，提供更精准的输出 |
权限隔离 | 最小权限原则，降低误操作风险 |
可复用性 | 跨项目复用成熟的 Subagent 配置 |
协作编排 | 多 Subagent 协同完成端到端工作流 |
2. Subagents 添加方法和使用方法
配置文件结构
在项目根目录创建或编辑
.claude/subagents.json：配置字段详解
字段 | 必填 | 说明 |
name | ✅ | 唯一标识符,推荐 kebab-case 命名(如 code-reviewer、test-writer) |
description | ✅ | 简述 Subagent 职责,用于帮助理解其用途 |
model | ❌ | Claude 模型版本(默认使用项目配置)。可选值: claude-opus-4-5-20251101(复杂推理)、claude-sonnet-4-20250514(平衡性能)、claude-3-5-haiku-20241022(快速响应) |
instructions | ✅ | 系统提示词,定义专家角色和行为规范。应明确包含:角色定位、分析维度、输出要求、注意事项 |
tools | ❌ | 可用工具数组。可选值: bash(执行命令)、file_editor(读写文件)、web_search(网络搜索)、notion(Notion 操作)、mcp(MCP 工具) |
permissions | ❌ | 权限控制对象。 allow:允许的操作列表(如["read", "write", "execute"]);deny:禁止的操作列表(优先级高于 allow) |
调用方式
方式一：自定义斜杠命令
方式二：CLI 直接调用
方式三：工作流内调用
在 Agent 工作流中嵌入 Subagent 调用逻辑。
3. 10个常用的 Subagents 示例
3.1 Code Reviewer（代码审查）
使用场景：PR 合并前代码审查、代码质量把关
3.2 Documentation Generator（文档生成）
使用场景：API 文档自动生成、README 维护
3.3 Test Writer（测试编写）
使用场景：新功能测试用例编写、测试覆盖率提升
3.4 Security Auditor（安全审计）
使用场景：安全扫描、合规检查、漏洞排查
3.5 Performance Optimizer（性能优化）
使用场景：热点代码优化、算法效率提升
3.6 Refactor Assistant（重构助手）
使用场景：遗留代码重构、模块解耦
3.7 Bug Hunter（Bug 猎手）
使用场景：Bug 定位、异常分析
3.8 API Designer（API 设计师）
使用场景：新 API 设计、接口规范制定
3.9 DevOps Helper（DevOps 助手）
使用场景：流水线配置、容器化部署
3.10 Dependency Manager（依赖管理）
使用场景：依赖升级、安全补丁应用
4. 项目中灵活使用多个 Subagents
场景示例：新功能开发全流程
场景示例：遗留系统改造
多 Subagent 协作配置示例
工作流执行说明
pre-commit 工作流（代码提交前触发）：
- code-reviewer 首先执行，分析待提交代码的质量、可读性和规范遵循度
- security-auditor 随后执行，扫描潜在安全漏洞和敏感信息泄露
- 两者均通过后，代码方可提交
post-feature 工作流（功能开发完成后触发）：
- test-writer 首先执行，根据新增功能自动生成单元测试和集成测试
- doc-generator 随后执行，更新 API 文档、README 和行内注释
- 确保功能交付时测试和文档同步完成
执行顺序原则：
- 只读型 Subagent（如 reviewer、auditor）可并行执行
- 写入型 Subagent（如 test-writer、doc-generator）应串行执行，避免文件冲突
- 依赖关系决定顺序：先分析后生成，先审查后修改
5. Claude Code 内置 Agent
Claude Code 提供多个开箱即用的内置 Agent，无需额外配置即可使用：
核心内置 Agent
Agent 名称 | 功能描述 | 典型用途 | 调用方式 |
Task | 通用任务执行代理，可处理多步骤复杂任务 | 项目初始化、批量操作、工作流编排 | /task 或自然语言描述任务 |
Bash | 执行 shell 命令和脚本 | 运行构建、测试、部署脚本 | 直接输入命令或 /bash |
File Editor | 读取、创建、编辑文件内容 | 代码编写、配置修改、文档更新 | 自动识别文件操作意图 |
Web Search | 搜索网络获取最新信息 | 查询文档、API 参考、问题解决方案 | /search 或提问时自动触发 |
Memory | 跨会话记忆管理，存储项目上下文 | 保存项目偏好、编码规范、常用配置 | /memory 管理记忆内容 |
MCP Tools | 调用 Model Context Protocol 工具 | 连接外部服务（数据库、API、文件系统） | 配置 MCP 后自动可用 |
Think | 深度思考模式，用于复杂推理 | 架构设计、问题分析、方案评估 | /think 或复杂问题自动启用 |
Compact | 上下文压缩，优化长对话性能 | 长会话管理、减少 token 消耗 | /compact 手动触发 |
开发辅助 Agent
Agent 名称 | 功能描述 | 典型用途 | 调用方式 |
Read | 读取文件内容，支持多种格式 | 查看代码、配置文件、日志分析 | 自动识别或 /read <path> |
Write | 创建或覆写文件内容 | 新建文件、完整替换文件内容 | 自动识别或 /write <path> |
Edit | 精确编辑文件的特定部分 | 代码修改、局部更新、重构 | 自动识别编辑意图 |
Glob | 文件模式匹配和搜索 | 查找特定类型文件、批量操作准备 | /glob <pattern> |
Grep | 在文件中搜索文本模式 | 代码搜索、查找引用、定位定义 | /grep <pattern> 或自动识别 |
LS | 列出目录内容 | 项目结构查看、文件导航 | /ls <path> 或自动识别 |
Tree | 显示目录树结构 | 项目架构概览、依赖分析 | /tree 或自动识别 |
Git 集成 Agent
Agent 名称 | 功能描述 | 典型用途 | 调用方式 |
Git Status | 查看工作区状态 | 检查未提交更改、暂存状态 | git status 或自动识别 |
Git Diff | 查看代码差异 | PR 审查、变更分析、回归检测 | git diff 或自动识别 |
Git Log | 查看提交历史 | 变更追溯、版本分析、贡献统计 | git log 或自动识别 |
Git Commit | 创建提交 | 保存更改、生成提交信息 | /commit 或 git commit |
PR Comments | GitHub PR 评论集成 | PR 审查、代码讨论、问题跟踪 | /pr-comments 或配置后自动 |
分析与诊断 Agent
Agent 名称 | 功能描述 | 典型用途 | 调用方式 |
Analyze | 代码分析和理解 | 代码审查、架构理解、依赖分析 | 自动识别分析意图 |
Debug | 调试辅助和错误分析 | 错误定位、堆栈分析、根因查找 | 自动识别错误信息 |
Explain | 代码解释和文档化 | 代码理解、技术概念说明、教学 | /explain 或自然语言提问 |
Summarize | 内容摘要和总结 | 文档总结、会议纪要、代码概览 | /summarize 或自动识别 |
Review | 代码审查和质量检查 | PR 审查、代码质量分析、最佳实践检查 | /review 或自动识别 |
会话管理 Agent
Agent 名称 | 功能描述 | 典型用途 | 调用方式 |
Clear | 清除当前会话上下文 | 开始新任务、释放内存 | /clear |
Reset | 重置会话状态 | 恢复默认配置、清除临时设置 | /reset |
Resume | 恢复上次会话 | 继续未完成任务、加载历史上下文 | /resume |
Undo | 撤销最近操作 | 回滚文件修改、撤销命令 | /undo |
History | 查看操作历史 | 审计追溯、回顾操作 | /history |
配置与帮助 Agent
Agent 名称 | 功能描述 | 典型用途 | 调用方式 |
Config | 查看和修改配置 | 调整设置、查看当前配置 | /config |
Model | 切换 Claude 模型 | 根据任务复杂度选择模型 | /model <name> |
Help | 查看帮助信息 | 了解命令用法、功能查询 | /help 或 /help <command> |
Version | 查看版本信息 | 检查当前版本、更新检测 | /version |
Init | 初始化项目配置 | 新项目设置、创建 .claude 目录 | /init |
内置 Agent 详细使用示例
Task Agent 示例：
Bash Agent 示例：
Memory Agent 示例：
Think Agent 示例：
内置命令快速参考
命令 | 功能 | 常用参数 |
/task | 启动多步骤任务 | 任务描述文本 |
/bash | 执行 shell 命令 | 命令字符串 |
/search | 网络搜索 | 搜索关键词 |
/memory | 记忆管理 | save / list / clear |
/think | 深度思考模式 | 问题描述 |
/compact | 压缩上下文 | 无参数 |
/help | 查看帮助信息 | 无参数或命令名 |
/clear | 清除当前会话 | 无参数 |
/config | 查看/修改配置 | 配置项名称 |
/model | 切换模型 | 模型名称 |
内置 Agent 协作模式
模式一：搜索 + 思考 + 执行
适用场景：需要外部知识支撑的复杂任务
模式二：编辑 + 测试 + 修复循环
适用场景：TDD 驱动开发、Bug 修复迭代
模式三：分析 + 记忆 + 执行
适用场景：新项目初始化、建立工作规范
内置 vs 自定义 Subagent 对比
维度 | 内置 Agent | 自定义 Subagent |
配置成本 | 无需配置，开箱即用 | 需要编写 JSON 配置文件 |
职责范围 | 通用功能，覆盖广泛场景 | 专注特定领域，高度定制化 |
指令精度 | 通用系统提示词 | 项目专属提示词，更精准 |
权限控制 | 统一权限策略 | 精细化权限隔离 |
工作流集成 | 手动编排调用 | 可配置自动化工作流 |
适用场景 | 日常开发、快速原型 | 团队协作、标准化流程 |
最佳实践：日常开发使用内置 Agent 快速完成任务；团队协作和重复性任务使用自定义 Subagent 确保一致性。两者可组合使用——自定义 Subagent 内部可调用内置工具。
6. 注意事项
设计原则
原则 | 说明 |
单一职责 | 每个 Subagent 只做一件事，避免职责混杂 |
最小权限 | 只授予完成任务所需的最小工具和权限集 |
清晰指令 | 系统提示词要明确、具体，定义专家身份和行为边界 |
合理命名 | 使用 kebab-case，名称应体现职责（如 code-reviewer） |
模型选择策略
任务类型 | 推荐模型 | 说明 |
复杂分析、架构设计 | claude-opus-4-5-20251101 | 需要深度推理 |
标准代码生成、审查 | claude-sonnet-4-20250514 | 平衡性能与成本 |
简单格式化、分类 | claude-3-5-haiku-20241022 | 快速响应、低成本 |
常见问题
权限冲突：多个 Subagent 同时写入同一文件可能导致冲突。建议在工作流中串行调用写入类 Subagent。
指令模糊：过于宽泛的 instructions 会降低输出质量。应明确：专家角色、分析维度、输出格式。
过度拆分：Subagent 过多会增加协调成本。控制在 5-10 个核心角色为宜。
调试技巧
- 日志追踪：启用详细日志查看 Subagent 调用链
- 逐步验证：先单独测试每个 Subagent，再组合工作流
- 权限检查：确认
permissions配置与实际需求匹配
- 模型回退：复杂任务失败时尝试升级模型版本
