Claude Code 里写第一个 subagent：3 层 9 步，把长 session 的脏 context 关进独立窗口

Claude Code session 跑 3-4 小时后会发生什么：回复变模糊。模型忘掉一小时前做的决定。代码从你开头定的模式漂走。context window 不是空的——是塞满了 test log、文件 dump、永远不会再看的搜索结果，噪声正在淹没信号。

多数人的反应是杀掉 session 重新开，把已经搭起来的一切扔掉换清晰度。

有更好的打法：把那个"堵住的、健忘的"session 改造成一条干净的主线程，让 specialist worker 把脏活拿到旁边去干。

Riley West 给出了一条基于 Anthropic 官方 Claude Code 文档、内置 agent、2026 年中真实存在的配置字段的 roadmap。没有发明的 flag，没有画饼的 feature。路径分 3 层：基础（subagent 是什么、怎么建一个）、隐藏杠杆（memory、scoped MCP、hooks）、生产层（并行、串行、知道何时不委派）。

9 步。3 层。一条永远不会 foggy 的主线程。

第 1 层 — 基础

Step 1. 先用内置 agent

在写一行 config 之前要知道：Claude Code 已经自带 subagent。Explore 是跑在 Haiku 上的快速 read-only agent，处理文件发现和代码库搜索；Plan 在 plan mode 时收集 context；general-purpose 处理需要既探查又编辑的多步工作。

subagent 整个存在的意义：把搜索、test 输出、log 处理这些 verbose 工作关进它自己独立的 context window，主对话只看到摘要。

错误是直接冲去造自定义 agent。先花几个 session 看 Explore 怎么做活。你会注意到你的主 context 保持干净，因为读密集的搜索从来不碰它。

有效：让 Explore 处理"X 在哪里定义"这类问题，别在主线程里 grep
有效：用 general-purpose 处理研究+编辑混合的自包含任务
避免：为一个内置已经做好的事造自定义 agent

Step 2. 用交互命令建第一个

最快的路是交互命令，不是手写 YAML。

/agents

开 tabbed interface。切到 Library tab，选 Create new agent，选 Personal（存到 ~/.claude/agents/，所有 project 都生效），然后选 Generate with Claude 描述你要什么：

A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

Claude 帮你写 identifier、description、system prompt。这样建的 agent 立即生效——不需要重启。

有效：让 Claude 写第一稿，然后改文件
避免：凭记忆手写 frontmatter——总会写错字段名
Pro tip：直接在磁盘改文件要重启 session；用 /agents 建的不要

Step 3. 读懂文件格式

subagent 默认继承主对话所有工具，除非你显式拒绝。对 code reviewer 这是危险的：你想它读和分析，永远不要它默默重写你的文件。下面是交互流程背后的最小文件：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

只有 name 和 description 必填。tools 是 allowlist；disallowedTools 是 denylist（例如 disallowedTools: Write, Edit 留所有工具但禁文件写）。Markdown body 变成 system prompt——subagent 拿到的是它加基本环境信息，不是完整 Claude Code system prompt。

有效：tools: Read, Grep, Glob, Bash 给一个能看不能碰的研究者
有效：把 description 写细——Claude 用它决定何时委派
避免：在你打算保持 read-only 的 agent 上省略 tools

第 2 层 — 隐藏杠杆

Step 4. 打开 memory

subagent 每次调用默认从空的 context 开始。memory 字段改这件事——它给 agent 一个跨 session 存活的目录，在那里积累 pattern、convention、recurring issue。

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---

You are a code reviewer. As you review code, update your agent memory
with patterns, conventions, and recurring issues you discover.

scope 选 user（所有 project，存 ~/.claude/agent-memory/）、project（可走版本控制共享）、local（项目内、不进版本库）。memory 开启后，Read/Write/Edit 自动启用，启动时 MEMORY.md 的前 ~200 行会注入 agent prompt。

Before：每次 review 从零开始；agent 每次重新推导你的命名约定
After："Review this PR, and check your memory for patterns you've seen before"——它已经知道
Pro tip：project 是推荐默认；让 agent 的知识成为团队资产

Step 5. 把 MCP server 限到子 agent

MCP tool description 光是被连接就在吃主对话 context。如果只有你的 browser-tester 需要 Playwright，把它 inline 在那个 agent 上——agent 启动时连、结束时断，父对话永远不为它付 token。

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

每条 entry 要么是 inline 定义（完整 config），要么是一个字符串引用已配置的 server（像上面 github 那个，共享父的连接）。

有效：给只有子 agent 需要的重型 MCP server 做 inline 定义
有效：对整个 session 都要用的 server 用字符串引用
避免：把冷门 server 塞进 .mcp.json——它会让每个 conversation 的 context 膨胀

Step 6. 用 hooks 做细粒度策略

有时你想允许工具的部分能力。数据库 agent 应该跑 SELECT 但永远不 DROP。tools 字段表达不了这个——hook 能。它在每次匹配的工具调用前跑脚本，可以 block。

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

脚本从 stdin 读 JSON 里的 command，exit code 2 阻断写入：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi
exit 0

有效：exit code 2 阻断并把错误消息回给 Claude
避免：想用 tools 字段强制 SQL 级安全——它看不到 command 内容
Pro tip：在 Windows 上用 PowerShell 写脚本，并在 hook entry 加 shell: powershell

第 3 层 — 生产

Step 7. 并行跑独立调查

对独立调查，同时 spawn 几个 subagent。各自在各自 context 里工作；Claude 把结果拼接。

Research the authentication, database, and API modules in parallel using separate subagents

这只在路径互不依赖时成立。而且有真代价：多个 subagent 各回详细结果，那些结果全落回主 context。

有效：并行真正独立、读密集的调查
避免：并行 agent 但它们的发现互相依赖
Pro tip：subagent-heavy workflow 烧 token 比单线程多得多——Anthropic 自己给的数字是约 7x。预算紧时单线程

Step 8. 主线程串行 chain

对串行工作，让 Claude 顺序跑 agent。每个跑完回到 Claude，Claude 把相关 context 传给下一个。

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

注意结构上限：subagent 不能 spawn 其它 subagent。需要嵌套委派，从主对话 chain，或改用 Skills。

有效：Reviewer → optimizer、或 spec → implementer → tester，从主线程编排
避免：设计假设"agent 能启自己的子 worker"的 workflow。它不能
Pro tip：把 project agent（.claude/agents/）check 进版本控制，让整个团队用同一条 pipeline

Step 9. 知道何时不委派

最高级的技能是克制。Subagent 从空白启动，花时间收集 context——错的任务上那延迟是浪费。

用主对话当：工作需要频繁来回、多阶段共享重 context、你在做一个快而针对性的修改。

用 subagent 当：任务产生你不需要的 verbose 输出、你想强制工具限制、工作自包含且返回干净摘要。

有效：用 subagent 跑"跑测试套件只汇报失败和错误"
避免：用 subagent 做五行修改——你花 90 秒 context-gathering 换 15 秒打字
Pro tip：对已经在你 conversation 里东西的快问，用 /btw——它看得到你的 context、没工具、用完丢弃不污染历史

镜像错误

上面那张清单的镜像。每一条都会悄悄吃掉你来这里的收益。

让每个任务都跑在主线程。Context 塞满 log 和 dump，到第三小时模型忘掉第一小时的决定
跳过内置、手卷所有 custom agent。一个下午你重建了 Explore，更烂
在 reviewer 上省略 tools。它"贴心地"重写了你没要它碰的三个文件
永远不开 memory。Agent 每次都重新学同样的约定，无穷无尽
把所有 MCP server 塞进 .mcp.json。每个 conversation 都背着它永远不会用的 server 描述
想用 tools 字段强制 SQL 安全。它读不到 command 内容，DROP 滑过去
紧 token 预算上 spawn 十个并行 agent。午饭前撞 rate limit，体会 7x 是什么意思
设计一个 subagent spawn subagent 的 workflow。它默默什么都不做，因为不可能
委派那个五行修改。90 秒 context-gathering 换 15 秒打字
改了磁盘上的 agent 文件奇怪为什么没生效。磁盘编辑要重启，你没重启

真要说的

一群 agent 不是更多 model，是更多结构。赢从来不是"更聪明的 Claude"——是"更干净的主线程，脏活在 fence 起来的独立 context 里，只回那些值得回的东西"。

Explore 替你挡掉搜索、scoped reviewer 只读不写、memory-backed agent 不用从零开始、chain 把临时 prompt 变成可重复 pipeline。

挑一个你还没做的 step——最可能是 memory，几乎没人拉的那个——明天就加上。然后下一个。