一文了解Claude Code Subagent。
如果你用过 Claude Code 处理大型任务，大概遇到过这个问题：让它去搜索一遍代码库、分析日志、查一堆文件——然后所有这些内容全部堆进主对话的上下文窗口。等你真正开始写代码时，窗口已经被探索性工作的垃圾填了一半。
1. 什么是 Subagent
Subagent 是运行在独立上下文窗口里的专属助手。它有自己的 system prompt、自己的工具权限、自己的模型配置。
主 Claude 把一项任务委托给 Subagent，Subagent 在自己的上下文里独立完成，只把结果摘要返回给主对话。主对话的上下文窗口不会因为探索性工作膨胀。
核心价值在五个方面：
1）保护上下文：搜索代码库、分析日志这类工作产生大量中间数据，让 Subagent 吃掉这些数据，主对话保持干净
2）约束工具权限：只读的 Subagent 不会误改文件；审计类 Agent 不需要执行权限
3）配置可复用：一次定义，在所有项目里都能自动触发
4）模型路由控制成本：简单搜索任务用 Haiku，复杂推理用 Sonnet——在 Subagent 层面按任务特性选模型
5）专业化行为：给特定领域写专注的 system prompt，比通用 Claude 更精准
2. 内置 Subagent：Claude Code 自带的三个
Claude Code 开箱即带三个内置 Subagent，你不需要配置，它自动触发：
1）Explore（探索者）
模型：Haiku（快、低延迟）
权限：只读，无法写文件
用途：代码库搜索、文件发现、结构分析
触发时机：Claude 需要理解代码库但不需要修改时，自动委托给 Explore
触发粒度还有三档：quick（定向查找）/ medium（均衡探索）/ very thorough（全面扫描）
2）Plan（规划者）
模型：继承主对话
权限：只读
用途：在 Plan Mode 下，Claude 进入规划状态时，先派 Plan 去收集上下文
为什么只读：防止 Subagent 嵌套（Subagent 不能再生成 Subagent）
3）General-purpose（通用执行者）
模型：继承主对话
权限：全工具
用途：复杂多步骤任务，需要又探索又修改
另外还有两个幕后 Agent：claude-code-guide（Haiku，回答 Claude Code 功能问题）、statusline-setup（Sonnet，配置状态栏时启动），平时感知不到它们的存在。
3. 如何定义一个自定义 Subagent
Subagent 的本质是一个 Markdown 文件，放在特定目录里：
~/.claude/agents/ ← 个人级，所有项目生效
.claude/agents/ ← 项目级，只在这个仓库生效
文件格式：
---
name: code-reviewer
description: 当需要代码审查、发现潜在 bug、检查代码规范时使用。
model: claude-sonnet-4-5
tools: read
---
你是一个严格的代码审查专家。审查时关注：
1）潜在的 bug 和边界条件
2） 性能问题
3） 违反代码规范的写法
每个问题需说明：当前代码 → 问题原因 → 改进建议
----
最关键的字段是 description。Claude 根据 description 决定什么时候触发这个 Subagent——写得越清晰准确，触发越精准。description 的质量直接决定 Subagent 的实用性。
用命令创建也很方便：在 Claude Code 里运行 /agents，进入 Library → Create new agent，让 Claude 根据你的描述自动生成 identifier、description 和 system prompt。
4. 三种使用模式
1）自动委托（最常见）
不需要做任何事，Claude 根据任务匹配 Subagent 的 description 自动委托。你感知到的只是 Claude 说「我派了一个 Agent 去做这件事」。
2）显式调用
直接在对话里 @名字：
@code-reviewer 请审查 src/auth/ 目录下的所有文件
3）Fork 当前对话
把当前主对话的上下文 fork 成一个 Subagent，在 fork 里做实验性操作，不影响主线：
/fork
适合「我想试一种不确定的方案，但不想污染主对话」的场景。
5. 实际应该怎么用
一个典型的工程实践：
大型代码库里做一个新功能，任务链大概是：
1）先搜索相关代码在哪 → Explore（只读，Haiku，快）
2）制定修改方案 → Plan Mode + Plan Agent（只读，不误改）
3）实际写代码 → 主对话或 General-purpose（全工具）
4）提交前代码审查 → 自定义 code-reviewer（只读，Sonnet）
5）整个过程主对话的上下文里只有最终产出，不会被搜索结果、日志、中间文件污染。
#HOW I AI# #程序员#
