你将得到什么

• 一份可直接落盘的 finder.md（YAML frontmatter + 系统提示）
• 如何用自然语言 / @ 提及触发委托，并在 transcript 里认出 subagent 行
• 可选：用户级 Explore.md 覆盖内置 Explore，并钉 model: haiku
• 可选：CLAUDE_CODE_SUBAGENT_MODEL=haiku + CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1（force 需 v2.1.257+）

课前准备

1. 已完成上一课：Claude Code ≥ v2.1.293，且能成功切到 Haiku 5.5。
2. 主会话建议留在 Sonnet / Opus（规划与改代码）；把搜索、只读探查交给 Haiku subagent。
3. 本课不修改仓库业务代码；只新增/编辑 agent 定义文件。无真实 API Key；占位用 YOUR_…。

一、Subagent 是什么（对照结果）

官方定义要点：

• Subagent 是独立上下文里的专用助手：有自己的系统提示、工具集与权限；结果摘要回到主会话，避免把大段搜索刷屏塞进主对话。
• 定义文件是 带 YAML frontmatter 的 Markdown，放在：
  • 用户级：~/.claude/agents/（所有项目可用）
  • 项目级：.claude/agents/（建议进版本库给团队共用）
• 必填字段：name、description；常用可选：tools、model 等。
• model 可填别名 haiku / sonnet / opus / fable，或全名如 claude-haiku-5-5，或 inherit。

内置 Explore：只读代码搜索；官方明确：

A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to run exploration on a lower-cost model.

产品页也写：Haiku 5.5 适合做 coding / 明确任务的 subagent。

二、动手：创建用户级 `finder.md`

1. 建目录（若还不存在）

mkdir -p ~/.claude/agents

注意（官方）： 若会话开始时还不存在 ~/.claude/agents/，新建目录后需要重启 Claude Code，监视器才会加载；目录已存在时，增改文件一般几秒内生效、无需重启。

2. 写入定义

把下面整段保存为 ~/.claude/agents/finder.md：

---
name: finder
description: 只读代码库探查。文件发现、符号搜索、阅读源码并返回精炼结论。用户要求搜索/定位/解释现有代码且不改文件时主动使用。
tools: Glob, Grep, Read
model: haiku
---

你是只读探查代理。只使用 Glob、Grep、Read。

工作方式：
1. 先用 Glob / Grep 缩小范围，再 Read 关键文件
2. 向主会话只返回：结论、关键文件路径、必要时的短代码片段
3. 不要建议或执行写文件、改依赖、跑破坏性命令
4. 找不到时如实说明已搜路径与关键词，不要编造

字段说明（与官方 frontmatter 表一致）：

项目级写法相同，只是路径改为仓库内：

mkdir -p .claude/agents
# 将同一份内容保存为 .claude/agents/finder.md

优先级（同名时）：托管配置 > --agents CLI > 项目 .claude/agents/ > 用户 ~/.claude/agents/ > 插件（数字越小越高）。

3. 试跑一句委托

主会话请先切回你习惯的主力模型（示例）：

/model sonnet

然后用自然语言委托：

用 finder 代理在本仓库里找出所有 README 或 package.json 的路径，只返回路径列表与一句总结，不要改任何文件

也可以 @ 提及（输入 @ 从列表选 agent，或按官方形式）：

@agent-finder 搜索 src 下与 auth 相关的文件名，只读，给出路径与一句说明

对照结果（成功时你会看到）：

• Transcript 出现类似 finder(…) 的工具调用行（官方示例形如 code-improver(Suggest code improvements)）
• Subagent 只读探查后，主会话收到摘要（路径列表 + 短结论），而不是整仓库文件刷屏
• 主会话模型仍是你选的 Sonnet/Opus；探查侧按定义走 haiku（可用 /tasks 看 running subagent 的模型行；官方称 /tasks 显示模型需 v2.1.242+）
• 若提示找不到新 agent：确认文件路径、name/description 俱全，必要时重启 claude

三、可选：用同名文件覆盖内置 Explore

若你更想「一说探索就自动走 Haiku」，可写用户级（或项目级）Explore.md：

保存为 ~/.claude/agents/Explore.md：

---
name: Explore
description: 快速只读搜索与分析代码库。在需要发现文件、搜索符号、理解代码且不修改仓库时使用。
tools: Glob, Grep, Read
model: haiku
---

你是只读 Explore 代理。使用 Glob、Grep、Read 完成探查，向主会话返回精炼发现。
不要写入或编辑文件。

官方：用户/项目级同名 Explore 覆盖内置 Explore，并保留你写的 model 字段。

试一句：

帮我探索一下这个项目的目录结构，找出入口文件

对照结果： 主会话仍可能保持 Sonnet/Opus；探索工作落到你的 Explore（Haiku），结果以摘要返回。

不想覆盖时：删掉或改名该文件即可；也可用权限拒绝内置 Explore（进阶，见官方 Agent(Explore) deny），本课不展开。

四、可选：强制「所有」Subagent 用 Haiku

仅设 CLAUDE_CODE_SUBAGENT_MODEL 时，它是默认值：单次调用参数或 frontmatter 里的 model（含 inherit）仍可覆盖它。

要强制每一个 subagent / teammate / workflow agent 都走同一模型，官方要求同时设置（force 需 Claude Code v2.1.257+）：

在 ~/.claude/settings.json（或项目 settings）加入：

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

说明：

• 两个都设时：subagent 跑在 CLAUDE_CODE_SUBAGENT_MODEL 指定的模型上
• force 打开后：忽略定义文件里的 model，Claude 也不能在启动 subagent 时另传模型
• 第三方云上若 haiku ≠ 5.5，把变量值改成 claude-haiku-5-5（或你的 provider ID）
• 改完后新开会话；跑 subagent 时用 /tasks 核对模型列

对照结果： 再委托 finder 或 Explore，/tasks 行上模型应为 Haiku（或你钉的全名）；取消 force 时删掉 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 或设回非 1，并视需要去掉 CLAUDE_CODE_SUBAGENT_MODEL。

五、和「主会话 `/model haiku`」的差别

官方还写：你在主会话用 /model 切换后，继承主会话模型的 subagent 会跟新模型；要让自定义 subagent 固定用小模型，就在定义里写死 model（或用上一节 force）。

六、本课自检清单

• ~/.claude/agents/finder.md（或项目级）存在，name + description 齐全，tools 仅只读，model: haiku（或 claude-haiku-5-5）
• 主会话在 Sonnet/Opus 下，自然语言或 @agent-finder 能触发委托并看到 finder(…) 行
• （可选）Explore.md 覆盖后，探索类请求走 Haiku
• （可选）settings 里 CLAUDE_CODE_SUBAGENT_MODEL + FORCE=1，且 CLI ≥ 2.1.257；/tasks 能核对模型
• 未把真实 API Key 写进 agent 文件或仓库

七、本课未覆盖（需要时查官方）

• Subagent 的 permissionMode、hooks、memory、isolation: worktree
• --agents JSON 一次性注入、插件分发 agents
• Agent teams / background agents / fork（/subtask）——与「自定义 Markdown subagent」不同层
• Messages API 的 Haiku 5.5 迁移（见 course 62）

来源

1. Create custom subagents · Claude Code Docs
2. Model configuration · Claude Code Docs
3. Claude Haiku · Anthropic