Claude回复太啰嗦？用Subagent打造你的专属AI团队

深夜两点，我盯着屏幕，看着Claude又一次给出了3000行的回复。我只是想让它帮我查一下代码里有没有安全隐患，结果它连重构建议、性能优化、测试用例全给我写了一遍。

说实话，当时我就想------能不能让它只关注代码审查，别扯那么多有的没的？

后来我发现，Subagent就是专门解决这个问题的。

Subagent到底是什么

简单说，Subagent就是你给Claude定制的专属助手。每个助手有自己的任务范围、工具权限，甚至用的模型都可以不一样。

它们住在你项目的.claude/agents/目录里，每个文件就是一个助手。文件结构挺简单：上面是YAML配置，下面是Markdown写的详细提示词。

yaml 复制代码

---
name: code-reviewer
description: 专门审查代码质量和安全隐患的助手
tools: [Read, Grep, Glob]
model: haiku
---

你是一个代码审查专家，专注于发现以下问题：
- 安全漏洞（SQL注入、XSS等）
- 性能瓶颈
- 代码规范问题

你只需要指出问题，不要动手改代码。

和普通的Claude对话比起来，Subagent有三个明显的不同：

专注------它只干你规定的事，不会跑题。你让它审查代码，它就只审查，不会顺手帮你重构。

受限------工具权限是你给的，它不能用你没授权的工具。一个只读的审查助手，根本没办法改你的文件。

可复用 ------配置文件放在项目里，团队成员都能用。新人入职，直接@code-reviewer就能开始干活。

为什么需要Subagent

老实说，我一开始觉得这东西是多此一举------直接跟Claude聊不就完了吗？

但用了一段时间之后，我发现确实香。

专注性

Claude本身太全能了，你问它代码问题，它可能会顺便给你讲最佳实践、推荐框架、甚至帮你写文档。这些东西有时候有用，但大部分时候只是噪音。

Subagent能让它专注在单一任务上。一个专门做代码审查的助手，不会给你写重构方案；一个专门写测试的助手，不会质疑你的架构设计。

成本优化

这个可能很多人没意识到------不是每个任务都需要用最贵的模型。

搜索、格式转换、简单的分析，用Haiku就够了，成本大概是Sonnet的三分之一。一个团队一个月下来，省的钱挺可观的。

并行处理

这才是我觉得最爽的地方。

你可以同时启动多个任务，让它们并行跑。比如写完一个功能之后，同时让一个助手跑单元测试、一个做代码审查、一个写文档。实际体验下来，效率提升非常明显。

可复用性

写好的配置文件，直接提交到Git仓库，团队成员都能用。项目积累下来的经验，变成了可执行的配置。

YAML配置详解

说了这么多，具体怎么写配置文件呢？

一个完整的Subagent配置有几个字段，但只有两个是必须的：

yaml 复制代码

---
name: blog-writer          # 必需：助手的唯一标识
description: 撰写博客初稿的专家  # 必需：简短描述，影响自动触发
tools: [Read, Write, Grep]  # 可选：工具权限，默认是全部
model: sonnet              # 可选：模型选择，默认继承主对话
---

# 提示词写在YAML下面
你是一个专业的博客写作者...

name ------助手的ID，用于调用时识别。最好起个能一眼看懂的名字，比如code-reviewer、test-writer。

description------这个很关键。Claude会根据描述来判断什么时候自动触发这个助手。如果你写"处理各种任务的通用助手"，那它基本永远不会被自动触发。

不好的写法：

yaml 复制代码

description: 一个帮手

好的写法：

yaml 复制代码

description: 深度调研博客主题，生成结构化内容规划文档

tools------工具权限列表。没配置的话默认能用所有工具，但这其实不太好（后面会讲）。

model ------选择用哪个模型。haiku便宜快速，sonnet是默认的平衡选择，opus质量最高但最贵。

工具权限控制

这一块我踩过坑，值得单独说说。

刚开始我图省事，所有Subagent都用默认的全权限。结果有一次，一个本来只应该做代码分析的助手，顺手帮我改了几个文件------改错了。

从那以后，我就开始认真对待工具权限了。原则挺简单：只给必需的权限，不多给。

常见的工具权限组合：

任务类型	推荐工具组合
只读分析	`Read, Grep, Glob`
搜索研究	`Read, WebSearch, WebFetch`
内容编辑	`Read, Edit`
内容创建	`Read, Write, Edit`
全权限	`All tools`（谨慎使用）

一个实际的对比：

不好的配置：给代码审查助手太多权限

yaml 复制代码

---
name: code-reviewer
tools: []  # 空数组 = 全权限，这样不太安全
---

好的配置：只给只读权限

yaml 复制代码

---
name: code-reviewer
tools: [Read, Grep, Glob]
---

只读的审查助手，根本没办法误改你的代码。这种约束，反而是一种保护。

三种调用方式

配置写好了，怎么调用呢？有三种方式：

自动触发

如果你在description里写得够清楚，Claude会自动判断什么时候该调用。比如描述写"处理所有与代码审查相关的请求"，那你说"帮我审查一下这个PR"，它就会自动触发。

@-mention

最直接的方式，直接@agent-name就行：

css 复制代码

@code-reviewer 帮我看看这个函数有没有问题

Task工具

编程式调用，适合更复杂的场景：

ini 复制代码

Task(subagent_type="code-reviewer", prompt="审查src/目录下的所有文件")

方式	语法	适用场景	特点
自动触发	无需显式调用	明确关键词	方便但可能误触发
Task工具	`Task(subagent_type="name")`	编程式调用	精确控制
@-mention	`@agent-name`	交互式使用	直观但需要记名字

我个人最常用@-mention，简单直接。自动触发有时候会误判，Task工具在复杂工作流里才用得上。

Multi-Agent协作

说到这里，还只是单个助手的用法。Subagent真正强大的地方，是多个助手协作。

顺序模式

我用得最多的是顺序模式，特别适合内容创作类的工作流：

less 复制代码

用户输入主题
    |
@blog-planner 做调研、写大纲
    | 输出规划文档
@blog-writer 读取大纲、写初稿
    | 输出初稿
@blog-editor 读取初稿、润色发布
    | 输出最终稿

每个助手只负责一个环节，前一个的输出是后一个的输入。清晰、可控、容易调试。

并行模式

并行模式就更爽了。写完一个功能之后，同时启动：

@test-writer 写单元测试
@code-reviewer 做代码审查
@doc-writer 写文档

三个任务并行跑，互不干扰。原来要串行做30分钟的事，现在10分钟搞定。

HITL模式（Human In The Loop）

还有一种模式，适合需要人工确认的场景：

less 复制代码

@planner 生成方案
    |
用户确认或修改
    |
@executor 执行方案

这种模式的好处是，关键决策点由人来把控，不会完全失控。

七个编写技巧

用了几个月Subagent，我总结了7个让配置更好用的技巧：

技巧1：描述要精准

description直接影响自动触发的准确性。

太模糊------几乎不会被自动触发：

yaml 复制代码

description: 一个通用的助手

精准描述------明确职责范围：

yaml 复制代码

description: 专门审查Python代码的安全漏洞和性能问题

技巧2：提示词要具体

别只说"你是一个代码审查专家"，要告诉它具体怎么审查。

太笼统：

markdown 复制代码

你是代码审查专家，帮用户审查代码。

具体指导：

markdown 复制代码

你是Python代码安全审查专家。

## 审查重点
1. SQL注入风险 - 检查所有数据库操作
2. XSS漏洞 - 检查用户输入的处理
3. 敏感信息泄露 - 检查日志和错误处理

## 输出格式
每个问题按以下格式报告：
- 文件：xxx
- 行号：xxx
- 风险等级：高/中/低
- 问题描述：xxx
- 修复建议：xxx

技巧3：工具最小化

前面说过了，只给必需的权限。少给权限不会让助手变笨，只是限制了它能做的事。

技巧4：模型选对

简单任务用Haiku，复杂任务用Sonnet。具体来说：

Haiku适合：搜索汇总、格式转换、简单分析、数据整理
Sonnet适合：复杂逻辑、创意内容、代码生成、推理分析

技巧5：测试要充分

写完配置之后，多试几种调用方式。自动触发好不好用？@-mention正不正常？边界情况怎么处理？

技巧6：文档要清晰

提示词本身就是文档。写得清楚的话，团队成员一看就知道这个助手是干什么的、怎么用。

技巧7：迭代要频繁

别想着一次就写完美。先写一个能用的版本，实际用一段时间，根据反馈慢慢调整。

常见错误避坑

讲完技巧，再说说我踩过的坑：

坑1：描述太模糊

写"通用助手"这种描述，Claude根本不知道什么时候该调用它。要写清楚具体负责什么。

不好：

yaml 复制代码

description: 帮助用户的助手

改进：

yaml 复制代码

description: 当用户提到"测试"、"单元测试"时，自动生成测试用例

坑2：工具权限过多

图省事给全权限，结果助手做了你不希望它做的事。特别是Write权限，给之前要想清楚。

不好：

yaml 复制代码

name: format-converter
tools: []  # 空数组 = 全权限

改进：

yaml 复制代码

name: format-converter
tools: [Read, Write]

坑3：提示词太长

Subagent的提示词也是算token的。写几千字的提示词，每次调用都要消耗这些token。保持简洁，只写必要的信息。

坑4：忘记设置model

不设置model的话，默认会继承主对话的模型（通常是Sonnet）。简单任务白白多花钱。

忘了设置：

yaml 复制代码

name: text-extractor
tools: [Read]

记得设置：

yaml 复制代码

name: text-extractor
tools: [Read]
model: haiku

坑5：循环调用

Agent A调用Agent B，Agent B又调用Agent A。这种死循环会一直跑下去，直到超时或者你强制停止。

正确：A -> B -> C 错误：A -> B -> A

坑6：没有错误处理

Subagent也会失败。在工作流里加上错误处理逻辑，失败了能及时发现。

坑7：配置没有版本控制

配置文件要提交到Git。改了配置出了问题，能回滚到之前的版本。

实战案例：博客写作系统

说了这么多理论，来看个实际的例子。

我自己在用的博客写作系统，由三个Subagent组成：

系统架构

ini 复制代码

用户提供主题
    |
blog-planner: 调研+规划（20分钟）
    | 输出：docs/[主题]-内容规划文档.md
blog-writer: 撰写初稿（40分钟）
    | 输出：docs/[主题]-初稿.md
blog-editor: 润色优化（20分钟）
    | 输出：docs/[主题]-最终稿.md

blog-planner（规划师）

yaml 复制代码

---
name: blog-planner
description: 深度研究主题并创建内容规划文档
tools: [Read, Write, Grep, WebSearch, WebFetch]
model: sonnet
---

你是内容规划师，负责：
1. 使用WebSearch研究主题的最新趋势
2. 分析目标受众和痛点
3. 设计文章结构和SEO策略
4. 输出规划文档到docs/文件夹

blog-writer（作者）

yaml 复制代码

---
name: blog-writer
description: 根据规划文档撰写博客初稿
tools: [Read, Write, Grep]
model: sonnet
---

你是内容作者，负责：
1. 读取规划文档
2. 按照大纲撰写完整初稿
3. 确保内容人性化、去AI味
4. 输出初稿到docs/文件夹

blog-editor（编辑）

yaml 复制代码

---
name: blog-editor
description: 编辑初稿并优化人性化表达
tools: [Read, Edit]
model: haiku
---

你是内容编辑，负责：
1. 读取初稿
2. 检查并消除AI味表达
3. 增强人性化和可读性
4. 输出最终稿到docs/文件夹

工作流程很简单：

bash 复制代码

# 第1步：规划
@blog-planner Claude Code Subagent使用技巧

# 第2步：撰写
@blog-writer

# 第3步：编辑
@blog-editor

每个环节都有明确的输入输出，出问题了容易定位。

成本优化建议

最后说说成本的事。

Haiku和Sonnet的价格差大概是3倍左右（具体价格请参考Anthropic官网）。一个典型的博客写作任务，如果合理分配模型，能省下不少钱。

模型选择策略

我的建议是：

用Haiku的场景

搜索和信息汇总
简单的格式转换
数据整理和分类
代码审查（只读分析）

用Sonnet的场景

内容创作（博客、文档）
复杂的代码生成
需要推理的分析任务
对质量要求高的场景

模型对比参考

模型	特点	适合场景
Haiku	快速、便宜	简单任务
Sonnet	平衡、默认选择	复杂任务
Opus	质量最高、最贵	极致质量

Opus我几乎不用，除非是特别重要、对质量要求极高的任务。日常工作Sonnet足够了。

省钱口诀

记住这几条：

能用Haiku就别用Sonnet
能限制工具就别给All tools
能精简提示词就别写太长
能限制输出就别让它随便发挥

写在最后

说白了，Subagent不是什么黑科技，就是把Claude的能力按需拆分。一个通才变成一个专家团队，每个专家只干自己擅长的事。

如果你还在用"一个Claude打天下"的方式，我真的建议试试Subagent。花半小时写几个配置，能省下无数个"Claude又跑题了"的时刻。

核心就是几个原则：

一个agent只干一件事
只给必需的工具权限
简单任务用Haiku
提示词要具体清晰
多agent协作用文档传递

遇到问题别慌，多半是配置没写对。对照着这篇文章的7个技巧和7个错误，基本都能解决。

最后说一句：别追求完美配置，先用起来，慢慢迭代。

祝你早日组建自己的AI团队！