文档大纲

Claude Subagent 完全指南 + 4 个开箱即用模板

Claude Code 最近上线了一个让我眼前一亮的特性——Subagent（子代理）。它解决了主对话被无关细节塞满的痛点，让 Claude 真正像一支团队那样干活。这篇教程是我读完官方文档加上反复实测后的总结，覆盖原理、部署、用法、4 个开箱即用的 C++ 实战模板。

Subagent 是什么？

Subagent 就是 Claude 给你的"AI 副驾席位"。它是一个独立、有自己系统提示、自己工具白名单、自己上下文的 AI 助手，由主对话里的 Claude 在合适的时机自动调起，做完活只回一份精炼的摘要。

它的核心价值用一句话概括：让主对话的"脑子"不被无关细节塞满。

下面分四块讲清楚：价值、怎么部署、怎么用、最佳实践，以及 4 个完整的 C++ 实战案例。

一、Subagent 到底解决了什么问题？

先想象一个场景：你在 Claude Code 里写 C++ 代码，说"跑一下全套测试，把失败的列出来"。Claude 真的去跑了，结果返回 30 个测试文件、上万行日志——这些信息你大概率不会再看第二眼，但它们已经塞进了你的主对话上下文。

下一次对话，Claude 必须带着这些垃圾信息一起思考，响应变慢、要付的 token 也变多，甚至可能在某个时刻爆掉 context window。

Subagent 就是为了避免这种浪费。具体来说，它给你带来 5 个核心价值：

1. 保留主上下文（最常用）

跑测试、读日志、查文档、扫代码——这些"重操作"丢给 subagent，详细结果留在它的上下文里，只回一份摘要给你。主对话永远是干净的。

2. 强制安全约束

Subagent 可以被锁死只能用什么工具。比如你定义一个"只能读数据库、不能改"的 subagent，它就算被你引到错误的方向，也跑不动 UPDATE 语句。

3. 跨项目复用

一个写好的 code-reviewer subagent，放在 ~/.claude/agents/ 下，这台电脑上每个项目都能用。比每次手动塞提示词省事一万倍。

4. 行为专精化

普通 Claude 是"万能通才"，subagent 可以是"专才"——你可以给它一套专门针对 C++ 性能优化的系统提示，让它的输出比通用模式靠谱得多。

5. 成本控制

给一个简单的"扫一遍代码找错别字"任务挂 model: haiku，给"重构整个模块"挂 model: opus——该省的省，该猛的猛。

二、如何在 Claude 桌面端部署 Subagent

桌面端（macOS / Windows 桌面应用）和终端的 Claude Code 共用同一套 subagent 配置——文件位置一模一样。

2.1 三种存放位置（作用域）

位置作用域优先级
~/.claude/agents/用户级（本机所有项目）4
.claude/agents/项目级（仅当前仓库，建议 git 共享）3
--agents CLI 参数仅本次会话（临时测试用）2

建议：项目级 subagent 用 .claude/agents/ + 提交 git，团队共享；个人反复用的放 ~/.claude/agents/。

2.2 Subagent 文件长什么样？

一个 subagent 本质上就是一个 带 YAML frontmatter 的 Markdown 文件，文件名随便起（通常用 kebab-case），但 frontmatter 里的 name 字段才是真正标识它的东西。

---
name: cpp-code-reviewer
description: 审查 C++ 代码的安全性、性能和现代 C++ 习惯用法（modern C++ idioms）。在写完或改动 C++ 代码后主动使用。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名资深 C++ 代码审查员。请按以下步骤工作：

1. 用 git diff 查看最近改动
2. 聚焦被修改的文件
3. 按优先级给出反馈

审查清单：
- 是否有内存安全问题（裸指针、所有权不清晰）
- 是否使用了现代 C++（C++11/14/17/20）特性替代旧写法
- RAII 是否到位
- 异常安全性
- 性能热点（不必要的拷贝、虚函数滥用、锁粒度）
- 命名、注释、可读性

按严重程度分三档输出：Critical / Warning / Suggestion，每条都给出具体改进示例。

字段说明（只需要记几个常用的）：

  • name（必填）：小写+连字符，比如 cpp-code-reviewer
  • description（必填）：决定 Claude 何时自动调它，写得越具体越好；想让它"主动触发"就加"Use proactively"
  • tools：白名单，省略则继承主对话所有工具
  • disallowedTools：黑名单，比如 disallowedTools: Write, Edit 让它只能看不能改
  • model：可填 sonnet / opus / haiku / inherit，默认 inherit
  • permissionMode：可选 plan / acceptEdits / bypassPermissions 等
  • isolation: worktree：让 subagent 在隔离的 git worktree 里干活，不会污染你当前工作区

2.3 三种创建方式

方式 A：让 Claude 帮你写（最简单）

直接在桌面端对话里说：

在 ~/.claude/agents/ 下给我建一个 cpp-performance-reviewer subagent，专门审查 C++ 代码的性能瓶颈，建议改进方案。只读，不要写文件。用 Sonnet。

Claude 会自己把文件写好，你确认一下内容即可。

方式 B：手动创建

桌面端文件管理器里建 ~/.claude/agents/cpp-reviewer.md，把上面的模板贴进去改改，保存。

方式 C：CLI 临时定义

终端启动时直接传：

claude --agents '{
  "cpp-reviewer": {
    "description": "C++ 代码审查专家",
    "prompt": "你是一名资深 C++ 审查员...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

这种方式只在本次会话有效，适合临时测试或自动化脚本。

2.4 重要提示

桌面端启动后 subagent 文件是热加载的，改完几秒内生效，不用重启。但是有 2 个例外：

  • 第一次创建某个 agents 目录时，需要重启一次让它发现
  • --disable-slash-commands 启动的会话完全不监听

三、使用 Subagent 的三种姿势

3.1 自然语言（最常用，让 Claude 自己决定）

让 cpp-reviewer 帮我看看刚才那波改动的性能问题

Claude 根据 subagent description 里的描述判断要不要调它。

3.2 @-mention（强制指定，不想让 Claude 纠结）

输入 @ 会弹出选择器，选你的 subagent：

@cpp-reviewer 看一下这次重构有没有泄漏

适用场景：你想 100% 确定是某个 subagent 在干活，而不是被 Claude 临时换成 Explore 之类的通用代理。

3.3 全会话代理（–agent，最彻底）

启动时直接：

claude --agent cpp-reviewer

整场对话的主线程就变成了这个 subagent——用它的系统提示、它的工具集、它的模型。这种用法适合"我今天就要专心做 C++ 审查"这种场景。

四、Subagent 最佳实践（亲测有效的几条）

1. 写好 description 是关键

Claude 是根据 description 决定何时调你的 subagent 的。一个模糊的 description 会被无视：

# 差
description: Reviews code

# 好
description: Expert C++ code reviewer focused on memory safety, RAII, modern C++ idioms (C++17/20), and performance hot spots. Use proactively after modifying any C++ source file.

秘诀：说清楚做什么 + 触发时机（"after modifying" / "when failing"）+ 用 "Use proactively" 让 Claude 更愿意主动调。

2. 工具白名单越小越好

只读审查就别给 Write/Edit；调试就只给 Bash；SQL 查询只给 Bash + hook 校验。

# 只读 C++ 审查
tools: Read, Grep, Glob, Bash
# ❌ 没列 Write/Edit → 写不进去，安全

# C++ 性能调优（要改代码）
tools: Read, Grep, Glob, Edit, Write, Bash

3. 隔离大输出任务

明确告诉 Claude 把这些丢给 subagent：

用一个 subagent 跑全套测试，只把失败的 case 和错误信息报告给我。

用 subagent 去翻 vendor/ 下的所有 boost 头文件，看有没有用到的 deprecated API。

4. 并行研究，互不相关的任务同时开多个

同时用 subagent 研究 auth、database、API 三个模块，最后给我一份综合报告。

桌面端支持后台 subagent，任务并行跑，主对话还能继续编辑代码。

5. 链式 subagent

先用 cpp-reviewer 找性能问题，再用 cpp-optimizer 去修。

每个 subagent 只关心自己的事，最后主对话得到一条干净的处理链。

6. 用 isolation: worktree 避免污染主分支

跑大规模自动重构、加测试生成时，让 subagent 在独立 git worktree 里干活。

7. 用 memory 让 subagent 越用越聪明

---
name: cpp-reviewer
memory: project # 推荐：团队能共享
---

然后在系统提示里写：

完成审查后，把发现的模式和约定更新到你的 memory。

久而久之，这个 subagent 会"记住"你们项目的编码风格、反复出现的问题。

8. hooks 做精细控制

需要比白名单更细的规则时（比如"Bash 只允许 SELECT 不允许 DELETE"），写一个 PreToolUse hook：

hooks:
  PreToolUse:
  - matcher: "Bash"
    hooks:
    - type: command
      command: "./scripts/check-cpp-build.sh"

9. 团队共享 subagent

项目级的 .claude/agents/*.md 建议提交 git，并在 PR 里 review 每个新加的 subagent，像 review 普通代码一样 review prompt——它们就是配置即代码（Configuration as Code）。

10. 调试时记住的小工具

  • /doctor 会检查 subagent 文件的健康度（重复 name、缺失字段等）
  • ~/.claude/projects/{project}/{sessionId}/subagents/ 下有每次 subagent 调用的完整转录，出问题时翻这里

五、实战案例：4 个开箱即用的 C++ Subagent

下面给你四个开箱即用的 C++ 场景 subagent，可以直接复制到 ~/.claude/agents/ 下试。

案例 1：C++ 代码审查员（只读）

适用：PR 提交前 / 重大改动后的自动审查

---
name: cpp-reviewer
description: Expert C++ code reviewer. Use proactively after modifying any .cpp/.h/.hpp/.cc file. Focuses on memory safety, modern C++, performance, and exception safety.
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是一名资深 C++ 代码审查员，熟悉 C++11/14/17/20/23。
## 启动时执行
1. `git diff` 查看最近改动
2. 用 Glob 找到所有改动的 .cpp/.h/.hpp 文件
3. 逐文件审查
## 审查维度（按优先级排序）
### Critical（必须修）
- 内存安全：use-after-free、double free、buffer overflow
- 悬垂引用 / iterator 失效
- 数据竞争（多线程场景）
- 未捕获异常逃出 main 或线程边界
### Warning（建议修）
- 应该用 `std::unique_ptr` / `std::shared_ptr` 的地方用了裸指针
- 应该用 `std::string_view` / `std::span` 的地方用了拷贝
- 虚函数能 `final` 没 `final`、能 `override` 没 `override`
- 拷贝构造和移动构造语义不对等
- 锁粒度过粗、持有锁期间调用外部代码
- C 风格数组、`malloc/free` 残留
### Suggestion（可选）
- 范围 for 替代下标循环
- `constexpr` / `consteval` 替代宏
- `std::format` 替代手写字符串拼接
- structured bindings、`std::optional`、`std::variant` 替代特殊值/union
- 命名空间污染、`using namespace std;`
## 输出格式
## Critical
- `src/foo.cpp:42` — 描述问题
  当前：
  ```cpp
  // ...
  ```
  建议：
  ```cpp
  // ...
  ```
  理由：...
## Warning
...
## Suggestion
...
不要寒暄，直接给结论。

怎么用：

@cpp-reviewer 审查一下我刚改的 src/database/connection_pool.cpp

案例 2：C++ 性能优化专家（可改文件）

适用：发现性能瓶颈，让 subagent 提出 + 实施优化方案

---
name: cpp-perf-optimizer
description: C++ performance optimization specialist. Use when you have a profiled hot path, a slow function, or want to optimize memory allocations. Can edit files.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---
你是 C++ 性能优化专家。
## 工作流
1. 先读 profile 数据（perf / flamegraph / callgrind 输出的位置由用户告知，或者用 `Bash` 跑 `perf stat`）
2. 定位 hot path
3. 量化优化前后的改进（assignments, allocations, cache misses）
4. 一次性提出方案；用户确认后实施
## 优化清单
- **不必要的拷贝**：值传递 → const 引用 / 移动语义
- **动态分配**：能用 `std::vector::reserve` / `small_vector` / SSO string 就别裸 new
- **虚函数**：热路径上的 `virtual` → CRTP / `std::variant` / template
- **分支预测**：冷分支用 `[[unlikely]]`
- **缓存友好**：AoS → SoA，减少 false sharing（`alignas(64)`）
- **并发**：能用 `std::async` / 线程池就别自己起裸线程
- **编译期**：`constexpr` / template metaprogramming 替代运行期分支
## 输出要求
- 每个改动都标注：优化点 / 原理 / 预期收益
- 改动后给一段对比测试代码或 micro-benchmark 建议
- 不要破坏 ABI 接口（除非用户明确同意）

案例 3：C++ 构建/编译错误诊断器

适用：面对 g++/clang++ 几百行错误输出时

---
name: cpp-build-fixer
description: Diagnoses C++ build errors (g++, clang++, MSVC) and proposes minimal fixes. Use when compilation fails with cryptic template or linker errors.
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是 C++ 构建错误诊断专家。
## 工作流
1. 读取用户给的编译命令和完整错误输出（常常非常长）
2. **只回主对话一句：诊断结论 + 最可能的根因 + 具体修复建议**
3. 详细分析留在你自己的上下文里，不要让主对话被刷屏
## 你需要掌握的常见错误模式
- **模板**：SFINAE 失败、enable_if 误用、ADL 行为、C++20 concepts 未满足
- **链接器**：未定义引用通常是因为 inline / extern "C" / 命名空间 / 库顺序
- **MSVC vs GCC/Clang**：warning-as-error 行为差异、`/permissive-` 影响
- **头文件**：循环依赖、ODR 违规、宏污染、inline 函数在 cpp 中定义
- **ABI**：跨编译器（libstdc++ vs libc++）混用的 mangling 问题
- **C++ 版本**：`-std=c++17` 下用 `std::filesystem` 忘链接 `-lstdc++fs`（GCC 8/9）
## 输出格式
**根因**：一句话
**位置**：file:line（如果能从错误信息中提取）
**修复**：
```cpp
// 修改前
...
// 修改后
...
```
**说明**：为什么这么改
最多 5 条根因，按可能性排序。

为什么这个 subagent 价值大：MSVC 一旦爆模板错误，几千行输出很正常，主对话会直接被塞满。这个 subagent 把"看错误"的工作吞下，回你 5 句话。

案例 4：C++ 单元测试生成器

适用：给已有模块补单元测试

---
name: cpp-test-generator
description: Generates GoogleTest / Catch2 / doctest unit tests for C++ classes and free functions. Use proactively after writing new C++ code or when test coverage is low.
tools: Read, Grep, Glob, Write, Bash
model: sonnet
---
你是 C++ 单元测试生成专家。
## 风格
- 框架根据项目已有依赖选（grep `find_package(gtest)` 或 `Catch2` 决定）
- 测试名遵循 `Given_When_Then` 或 `MethodName_Condition_ExpectedBehavior`
- 每个测试独立、可重复、无外部依赖（必要时用 interface + fake）
## 覆盖要求
1. 正常路径（happy path）
2. 边界值（空容器、零、最大、INT_MAX、size_t 上溢）
3. 异常路径（应抛异常的输入）
4. 资源路径（RAII、泄漏）
5. 并发场景（如果函数声称是 thread-safe）
## 输出
- 测试文件路径遵循项目惯例（`tests/`、`test/`、`*_test.cpp` 同目录）
- 包含构建说明：CMake `add_executable` + `gtest_discover_tests` 或类似
- 自动跑一遍编译并修掉你自己的语法错误
不要生成无意义的"确保不崩溃"测试。每个断言都要有针对性。

怎么把这四个用起来

把上面四个 .md 文件扔到 ~/.claude/agents/ 下，重启一次桌面端，然后：

@cpp-reviewer 帮我审一下 src/database/connection_pool.cpp
刚改完，先用 cpp-test-generator 给 connection_pool 补一组单元测试，再用 cpp-reviewer 过一遍，最后用 cpp-perf-optimizer 看下有什么优化空间。

桌面端会自动把这串 subagent 串起来，主对话保持干净，结果以摘要形式回来。

六、一张表速查：什么时候用 subagent vs 主对话

场景推荐
跑测试、看日志、抓错误堆栈✅ subagent
大规模代码搜索 / 调研✅ subagent
多模块并行研究✅ subagent
需要严格工具约束✅ subagent
跨项目都要用✅ subagent
频繁迭代、需要 Claude 一直保持上下文❌ 主对话
快速小改❌ 主对话
延迟敏感的对话❌ 主对话（subagent 启动开销）
复用一段提示词做特定工作流考虑 Skill（在主对话上下文里跑）
简单"我没听懂刚才那句"/btw（主对话侧问，不污染历史）

七、一句话总结

Subagent = 隔离的上下文 + 专精的系统提示 + 受限的工具 = 一个不会弄脏你主对话的 AI 副驾。

下次再遇到"这段调试日志我以后不会再看但 Claude 必须先看完"的情况，就该考虑把它丢给 subagent 了。从一个简单的 cpp-reviewer 开始，慢慢养出一支专属于你工作流的 AI 团队。

阅读量： 273

网站备案号：沪ICP备2025137870号