Claude Code · Sub-Agents · Agent Memory
Claude Code Sub-Agents 实战：把一个聊天窗口拆成可协作的专家团队
英文原题：How To Use Claude Code Sub-Agents Better Than 99% of People。这期视频适合已经会用 Claude Code、但还在把研究、写作、测试和整理全部塞进同一段对话的人。
一、问题引入：为什么一个 Agent 不该包办所有事
视频开头提出的场景很具体：如果你不用一个 Claude Code 对话处理所有事情，而是让不同的子 Agent 分别写客户邮件、研究内容、准备会议、检查输出，并且这些角色还能随着使用积累偏好，工作流会发生什么变化？这不是把提示词拆得更花哨，而是把原本混在同一段上下文里的职责拆开。
在真实项目里，「一个聊天窗口解决一切」很快会遇到三个问题。第一，任务范围越大，模型越容易在研究、写作、执行和复盘之间来回跳。第二，权限太宽时，一个简单写作任务也可能意外读取或修改无关文件。第三，偏好和规则没有稳定落点，每次新会话都要重新解释。Sub-agent 的价值，就是把这些不稳定因素变成可命名、可审计、可复用的角色。
这期视频值得看的地方在于它不是只展示界面，而是同时讲了两条路线：一种是在 Claude Code 里用 /agents 自动生成；另一种是手动创建 .claude/agents、.claude/agent-memory 和对应 Markdown 文件。前者适合快速上手，后者才是真正理解 sub-agent 工作方式的入口。
二、核心概念解释：Sub-agent 本质上是有边界的专家提示词
1. 主 Agent 像业务负责人，子 Agent 像不同员工
视频把 Claude Code 比作业务负责人：你提出任务，它判断该交给哪个角色处理；子 Agent 则像研究助理、文案、QA 或运营人员。每个子 Agent 有自己的职责说明、工具权限、模型选择和记忆范围，完成后把清晰结果交回主 Agent，再由主 Agent 回到你面前。
2. Sub-agent 不是神秘程序，核心是 Markdown 指令
视频反复强调，子 Agent 本质上就是一个提示词文件。它通常包含 name、description、tools、model 和 instructions。这里最关键的是 description，因为主 Agent 会根据描述判断什么时候调用它；如果描述模糊，多个角色职责相似时就容易误触发。
3. tools 字段就是权限边界
视频把 tools 解释为权限：只读 Agent 可以读取和搜索，但不能修改；平衡 Agent 可以读、写、运行命令，但应避免危险动作；全权限 Agent 则适合高度结构化且你充分信任的任务。把 tools 想成团队成员的系统权限，比把它想成「功能列表」更准确。
视频中的核心判断可以转述为：不要让一个 Claude 对话永远扮演所有员工；把职责拆给不同子 Agent，主 Agent 才更像协调者。
4. memory 让角色跨会话变得稳定
默认情况下，新会话里的子 Agent 没有上一轮对话记忆。视频演示了给子 Agent 增加 project 级 memory，让它把语气偏好、反馈和任务规则写入 agent-memory 目录。这样你不必每次重复解释「邮件要兴奋一点」「客户 John 是谁」「输出要放进 outputs 文件夹」。
三、关键论点与实操步骤
步骤 1：用 /agents 快速创建第一个角色
视频的第一条路径是进入 Claude Code，在终端启动 Claude 后输入 /agents，选择创建新 agent，再选择 project 或 personal 作用域。project 更适合团队项目，因为角色定义会跟随项目存在；personal 更适合你自己的通用习惯。演示中选择 project，是为了让文件直接落在当前项目结构里。
步骤 2：先让 Claude 生成，再阅读它生成了什么
自动生成时，作者给了一个简单用例：根据 YouTube 视频想法生成 10 个选题和 hook。Claude 会询问工具、模型、颜色和 memory 作用域，然后创建对应的 agent 文件。这个过程很适合上手，但真正重要的是回头打开文件，看它到底写了哪些指令、工具和模型配置。
步骤 3：手动建立目录，理解真实文件结构
视频第二条路径是手动创建目录：先建立 .claude，再建立 agents 和 agent-memory，然后在 agents 里创建例如 email-writer.md 的文件。这个步骤解释了为什么 sub-agent 可以被版本控制、复制、审查和复用：它们不是只存在于 UI 里的配置，而是项目里的明文规则。
步骤 4：写清楚 description，因为它决定路由
示例 email writer 的 description 是「根据上下文写专业客户邮件」。作者说明，主 Agent 会读这个描述来判断是否应该调用该角色。工程上可以把 description 当作路由条件：它要足够具体，包含适用任务、输入条件和不适用范围，否则多个 agent 之间会出现职责重叠。
步骤 5：按任务成本选择模型
视频把模型选择分成三类：Haiku 快且便宜，适合读取文件、搜索代码、快速查找；Sonnet 平衡，适合大多数写作、代码 review 和日常任务；Opus 最强但更贵，适合困难调试、复杂推理和大型全栈任务。子 Agent 的好处是你不必给所有角色都配最贵模型，而是按职责分配算力。
步骤 6：用自然语言、显式提名或会话级默认来触发
视频列出三种触发方式。第一是自然语言，让 Claude 自己判断该用哪个 agent；第二是显式提到具体 agent，例如用 @ 或名字指定 email writer；第三是 session-wide，把某个 agent 设为整个会话默认。作者建议先从自然语言开始，再在角色变多时改用显式提名，因为后者最不容易误触发。
步骤 7：把输出和记忆分开放
作者演示生成客户邮件后，把产物移到普通 outputs 文件夹，而不是放在 .claude 内部。这是一个很实用的组织原则：.claude 里放角色定义、记忆、命令和技能；业务产物放在项目自己的 outputs、docs 或 src 目录里。这样规则和结果不会混在一起。
步骤 8：把反馈写入 memory，让角色逐步贴合你的业务
视频后半段演示让 email writer 在生成邮件的同时保存语气偏好。随后新会话再次调用该角色时，它会读取 memory 和 tone matching 文件，把之前的反馈带入新输出。对团队来说，这相当于把「隐性偏好」沉淀成可维护文档，而不是留在某一次聊天记录里。
四、对比表格 / 决策矩阵
| 做法 | 适用场景 | 优点 | 风险与建议 |
|---|---|---|---|
| 单一 Claude Code 对话 | 短任务、一次性探索、需求还不清楚的早期讨论。 | 启动最快，没有角色管理成本，适合快速试错。 | 任务一长就容易上下文混乱。进入重复流程后，应抽出固定子 Agent。 |
| 自动生成 sub-agent | 第一次搭建角色，或想让 Claude 帮你生成初版提示词。 | 路径简单，会引导你选择作用域、工具、模型和 memory。 | 生成结果未必符合团队标准。保存后必须人工检查 description、tools 和 instructions。 |
| 手写 Markdown agent | 有明确工作流、需要版本控制、需要团队共同维护的角色。 | 结构透明，可 review、可复制、可逐步演进，适合长期使用。 | 初期需要理解字段语义。建议从一个低风险角色开始，比如研究总结或只读代码审查。 |
| read-only agent | 资料检索、代码理解、会议准备、风险排查。 | 可以读取和搜索上下文，但不会改动文件，安全边界清晰。 | 不能直接落地修改。适合作为执行前的分析角色。 |
| balanced / full access agent | 代码生成、批量整理、自动化执行、结构化重复任务。 | 能把分析直接变成产物，效率高。 | 权限越大风险越高。full access 只用于你能清楚描述步骤且容易回滚的任务。 |
五、引用块：从提示词到团队制度
Sub-agent 最有价值的地方，不是让 Claude 看起来有更多人格，而是把职责、权限、模型和记忆从一次聊天里抽出来，变成项目可以维护的制度。
如果你只把 sub-agent 当作「更长的 prompt」，它很容易变成又一层复杂度。真正值得采用的场景，是那些反复发生、输入输出相对稳定、权限边界能定义清楚的工作：客户邮件、代码 review、研究摘要、QA checklist、会议准备、项目复盘。每个角色都应该回答三个问题：什么时候该用我、我能做什么、我绝不能做什么。
六、时间戳目录
/agents。.claude/agents 与 .claude/agent-memory。