翻完 Sub-agents 官方文档:我发现这几个功能值得学

最近认真翻了一遍 Claude Code 关于 Sub-agents 的官方文档，有点意外。

因为我发现很多功能我压根就没用过，甚至不知道存在。平时用 Sub-agents，就是让 Claude 自动派生一个子 agent 去跑任务，跑完了看结果。就这样。

但文档里其实藏着一些东西，单看文字不起眼，真正理解了会觉得——哦，原来可以这么用。

今天整理出来，都是那些「普通人大概不知道」的部分。

第一个：isolation: worktree

这个配置我第一次看到时没当回事，觉得只是个隔离选项。

---
name: my-agent
isolation: worktree
---

直到我理解了它背后的意思，才觉得有点惊喜。

开了这个配置之后，sub-agent 会在一个全新的 git worktree 里工作。什么意思？就是它会拿你当前分支的代码，在一个完全独立的工作区里跑，自己改、自己测，不管改成什么样，你的主分支动都不动。

这改变了一件事——你可以真的「放手」让 agent 去做有风险的操作，而不是在心里一直悬着「它要是改乱了怎么办」。

之前我们讨论过用 git worktree 跑并行 Claude Code 会话，本质是同一个思路。现在官方直接把这个能力内置进去了，一个配置字段就能开启。

第二个：tools: Agent(worker, researcher)

这个可能稍微难理解一点，但我觉得是这份文档里最被低估的功能。

通常我们给 agent 配置 tools，是限制它能不能用 Bash、能不能写文件。但你知道吗，tools 列表里还可以放其他 agent：

---
name: coordinator
tools: Agent(worker), Agent(researcher), Read, Bash
---

这意味着什么？这个 coordinator agent 只能调用 worker 和 researcher 这两个子 agent，它没法随意派生其他任何 agent。

普通用法里，Claude 可以在任务执行过程中随机决定要不要派生 agent、派什么 agent。但用这个字段，你实际上在定义一个结构化的 agent 团队拓扑——谁能调谁，谁负责什么。

要做复杂的多 agent 任务，这个比什么都重要。你不是在告诉 Claude「你可以用一些 agent 帮忙」，你是在设计一张组织架构图。

第三个：hooks 写在 frontmatter 里

hooks 这个机制很多人知道，可以在 settings.json 里配置，对 Bash 命令做前置拦截。

但大概很少人知道，hooks 可以直接写在 sub-agent 的 frontmatter 里：

---
name: db-reader
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

这个脚本会在 agent 每次调用 Bash 之前运行，如果检测到 INSERT、UPDATE、DELETE 这类写操作，直接 exit 2，Claude 就会放弃这次调用并告知原因。

重点不是这个拦截脚本本身，而是这个配置是绑定在 agent 上的。你不需要在全局 hooks 写一堆判断逻辑，而是把约束直接封装进 agent 的定义里。这个 agent 天然就是「只读的」，不管谁调用它、在什么场景下用，它就是不会执行写操作。

比在 system prompt 里写「你只能执行 SELECT 查询」要可靠得多。System prompt 里的限制是靠模型遵守，hooks 是硬拦截。

第四个：memory 持久记忆

---
name: code-reviewer
memory: project
---

就这一行。

开了之后，agent 会在 .claude/agent-memory/code-reviewer/ 目录下维护一个 MEMORY.md 文件。每次启动时，这个文件的前 200 行会自动注入进 agent 的 system prompt。跑完任务之后，你可以让 agent 把学到的东西写进去。

这意味着什么？

你的 code-reviewer agent 会随着时间积累越来越多关于你项目的「机构知识」——它知道你们团队对命名规范的偏好，知道哪个模块是历史遗留问题碰不得，知道上次代码审查里反复出现过什么问题。

大多数人把 agent 当一次性的工具，用完了就消失。memory 这个字段，让 agent 开始有了持续学习的能力。

文档里有几条实践建议我觉得值得摘出来讲一下。

第一，推荐用 project scope，不用 user。因为 project scope 的 memory 存在 .claude/agent-memory/ 下，可以 commit 进 git，整个团队共享同一份记忆。user scope 则只存在本地，是你个人的。

第二，memory 不会自动更新，要靠你或者 agent 主动去写。文档建议直接在 agent 的 system prompt 里加一句：

在你发现代码路径、项目规律、关键架构决策时，主动更新 agent memory。写简洁的笔记，记录发现了什么、在哪里。

这样 agent 就会在工作过程中自己维护这份知识库。

第三，你也可以在每次任务结束后，手动提示它：「你刚刚做的这件事，把你学到的东西存进 memory」。久了这份记忆就越来越有价值。

第五个：SubagentStart / SubagentStop 钩子

这是在主会话层面感知 sub-agent 生命周期的方式。

在 settings.json 里配：

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [{ "type": "command", "command": "./scripts/setup-db-connection.sh" }]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [{ "type": "command", "command": "./scripts/cleanup-db-connection.sh" }]
      }
    ]
  }
}

db-agent 启动的时候，自动建立数据库连接。db-agent 停止的时候，自动断开。

这看起来像是一个很工程化的功能，确实也是。但它打开了一件事——主会话和子 agent 之间可以有「环境联动」。你不只是在跑一段 AI 任务，你在调度一套有状态的工作流。

最后，Resume sub-agent

这个很多人不知道。

Sub-agent 的对话记录是独立存储的，文件在 ~/.claude/projects/{project}/{sessionId}/subagents/ 下。主会话做 compact 压缩，不影响 sub-agent 的对话历史。

所以你可以这样用：

“用 code-reviewer agent 看一下认证模块”

Agent 审查完了，你过了一段时间又想继续：

“接着刚才那次 code review，再分析一下授权逻辑”

Claude 会恢复那个 sub-agent 的完整上下文，而不是重新开始。就好像它从没关掉过一样。

写到这里，我回头想了一下，这些功能有一个共同的方向。

普通用法里，sub-agent 是「Claude 帮你做任务时用的工具」，你不需要管太多，Claude 自己决定用不用。

但这批进阶功能，说的是另一件事——你可以把 sub-agent 设计成一个有约束、有记忆、有生命周期感知的专业角色。它不只是「帮你跑任务」，它是你软件系统里一个有状态的组成部分。

这个思路的转变，我觉得比任何单一功能都重要。

你现在用的是哪种姿势？

官方文档地址：https://code.claude.com/docs/en/sub-agents 

/ 作者：火锅