子代理越多越好？Anthropic 官方先泼了冷水：你自建子代理的描述加起来超过 15,000 token，Claude Code 启动就警告你 这是 An… · @swordBluesy · TwKit

@swordBluesy

子代理越多越好？Anthropic 官方先泼了冷水：你自建子代理的描述加起来超过 15,000 token，Claude Code 启动就警告你 这是 Anthropic 的 Claude Code 官方文档《Create custom subagents》（创建自定义子代理）的开头部分（第 1 部分：它是什么、自带哪几个、五分钟做出第一个、文件放哪里）。先把结论放在前面，因为它反常识： 官方说每个子代理都跑在自己独立的上下文窗口里，有自己的系统提示词、工具权限和权限设置；它也发自己的请求，算进和主对话同一份用量额度。所以子代理不是“免费的分身”。而且 Claude 靠每个子代理的“描述”决定派谁干活，这些描述会占上下文，除内置的以外加起来超过 15,000 个 token，Claude Code 启动时就会给你一个带 token 总数的警告。 先说清词。 子代理（subagent），是专门处理某一类任务的 AI 小助手。一件边角活要是会把搜索结果、日志、文件内容一股脑塞满你的主对话，就交给它：它在自己的窗口里干完，只把摘要交回来。 上下文窗口（context window），是模型一次能看的内容容量。主对话塞满了，后面的回答就容易跑偏。 前置信息（frontmatter），是文件最上面用三条横线围起来的一小段设置，写名字、描述、工具、模型。 一个真实例子（官方 Quickstart）：对 Claude 说“创建一个个人的 code-improver 子代理，放在 ~/.claude/agents/，扫描文件并给出可读性、性能、最佳实践的改进建议，只读，用 Sonnet”，它就会替你把文件写好。 先把话说全： 官方明说：子代理在单个会话内工作。想同时跑很多互不相关的会话并在一处监控，要看 background agents；会话之间互相发消息，要看 cross-session messaging；由 Claude 派生并监督的一队会话，要看 agent teams。 官方列出的子代理好处有五个：保留上下文、强制约束（限制它能用的工具）、跨项目复用（用户级子代理）、让提示词专注某个领域、用更快更便宜的模型如 Haiku 控制成本。 这篇只讲官方文档的前半，后面的前置信息字段、权限模式、持久记忆、钩子、并行与分叉，放到后面几篇。 一、第一步：先认识 Claude Code 自带的子代理 Explore：快速、只读，专门搜索和分析代码库。工具是只读的，Write 和 Edit 被禁。Claude 需要搜索或理解代码库又不改东西时用它，调用时会选搜索深度：quick 对应定点查找，medium 是均衡探索，very thorough 是全面分析。想让探索更省钱，可以自己建一个叫 Explore 的用户或项目子代理并写 model: haiku，它会覆盖内置的。 Plan：在计划模式（plan mode）里用，先收集上下文再给你方案。同样只读，让研究输出留在独立窗口，主对话保持只读。 General-purpose：能探索也能动手的全能型，拥有子代理可用的全部工具，用于复杂研究、多步操作、改代码。 其他：claude（通用兜底，也是后台会话默认的代理）、statusline-setup（运行 /statusline 时用，Sonnet）、claude-code-guide（问 Claude Code 功能时用，Haiku）。 官方还说：Explore 和 Plan 启动时不带你的 CLAUDE.md 文件和 git 状态快照，为了又快又省；其他内置和自定义子代理两者都会加载，除非你在自定义子代理里设 omitClaudeMd。 想限制内置的：把某个类型写进 permissions.deny；想让 Claude 完全不派子代理，就把 Agent 工具本身写进 permissions.deny；只想去掉 Explore 和 Plan，设环境变量 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS 为 1（官方说要 Claude Code v2.1.198 或更高）。 二、第二步：五分钟做出你的第一个子代理（官方 Quickstart） 子代理本质是带前置信息的 Markdown 文件。 第一小步，让 Claude 替你创建：在 Claude Code 里说清你要什么、放哪里。官方示例提示词：Create a personal code-improver subagent in ~/.claude/agents/ 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. Make it read-only and have it use Sonnet. 第二小步，检查文件：打开 ~/.claude/agents/code-improver.md，确认前置信息和你说的一致。官方给的结果是：name 写 code-improver，description 写“Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.”，tools 写 Read, Grep, Glob，model 写 sonnet，正文是一段“你是代码改进专家，每发现一个问题，解释问题、给出当前代码、给出改进版本”的提示词。 第三小步，试用：对 Claude 说“Use the code-improver agent to suggest improvements in this project”。在记录里，委派会显示成一行工具调用，比如 code-improver(Suggest code improvements)。 成功标志：你看到这一行，并收到子代理返回的改进建议。 卡住怎么办：Claude 找不到新子代理，就重启 Claude Code 再试。官方说这只发生在 ~/.claude/agents/ 在会话开始前不存在的情况，因为运行中的会话发现不了新建的 agents 目录。 小提醒（官方）：/agents 现在只是提醒你让 Claude 去写或直接编辑 agents 目录；在 Claude Code v2.1.197 及更早版本，它会打开交互向导，有 Running 和 Library 两个标签。 三、第三步：选对放哪里（作用域） 官方给了优先级从高到低五档，同名时用优先级高的：托管设置（组织范围）；命令行 --agents 参数（仅当前会话）；.claude/agents/（当前项目）；~/.claude/agents/（你所有的项目）；插件的 agents 目录（插件启用的地方，优先级最低）。 项目子代理适合只属于某个代码库的，官方建议提交进版本控制，让团队一起改进。会从当前目录一路向上找到仓库根，路径上的每个 .claude/agents/ 都会被扫，同名取离当前目录最近的。用户子代理是你个人的，所有项目可用。两个目录都会递归扫描，可以分子文件夹，比如 agents/review/，但身份只看 name 字段；同一棵树下 name 要唯一，否则只会加载一个，由文件系统读取顺序决定，官方没写规则。 命令行子代理：用 claude --agents 加一段 JSON 启动，只在这次会话里有效，不存盘，适合快速测试或脚本。官方示例定义了 code-reviewer（描述“Expert code reviewer. Use proactively after code changes.”，工具 Read、Grep、Glob、Bash，模型 sonnet）和 debugger 两个。非交互模式下 --agents 还可以给一个 JSON 文件路径，官方说这个文件形式要 Claude Code v2.1.281 或更高；交互会话会拒绝文件路径。 插件子代理：随你安装的插件自动加载。官方的安全提醒：出于安全原因，插件子代理不支持 hooks、mcpServers、permissionMode 这三个字段，会被忽略；需要的话把文件复制到 .claude/agents/ 或 ~/.claude/agents/。 四、第四步：写文件、改文件 文件格式是上面一段 YAML 前置信息，下面是 Markdown 的系统提示词。官方说 Claude Code 会监视 ~/.claude/agents/ 和 .claude/agents/，你新增或编辑文件几秒内就会被识别，下一次委派用新定义，不用重启。三种情况仍要重启：某个作用域第一次新建 agents 目录；用 --add-dir 或 /add-dir 加进来的目录里的 agents；用 --disable-slash-commands 启动的会话。 五、开头那条“描述别写长”的做法 官方建议：删短每个子代理的 description，把细节挪进它的系统提示词，因为系统提示词只在这个子代理运行时才加载。 收藏版：5 步速查 1. 先用自带的 Explore 和 Plan，别急着自建。 2. 要建就对 Claude 说清用途、放哪、只读还是能改。 3. 打开 ~/.claude/agents/ 下的 .md 文件，核对 name、description、tools、model。 4. 对 Claude 说“Use the xxx agent to ...”试用，看到委派那一行才算成功。 5. description 写短，细节放进系统提示词。 原文：Anthropic（由 S1哥 编译） S1哥观点 这篇文档最狠的地方，是它在教你建子代理的第一页，就先告诉你代价：每个子代理的描述都要占主对话的上下文，建得越多，占的上下文越多。我之前置顶的那篇子代理文章讲的是“别乱用”，这里是同一个意思的另一面：别乱建。 真正的信号是，子代理像公司的岗位，每开一个岗位都要写岗位说明书、占预算、占沟通成本。先用自带的 Explore 和 Plan，确实反复在同一类活上重复提示词，再建自己的。 评论区二选一：你现在装的自定义子代理，是不到 3 个，还是已经超过 5 个？顺便报一下你最常用的那个叫什么。这是 Claude 全家桶小白系列第10篇（《Create custom subagents》第 1 部分），前几篇在我主页，关注 @swordBluesy。 今天送：Claude Code 子代理起步包（官方 Quickstart 提示词、作用域速查表、避坑清单），评论区直接拿。

曝光 353 · 评论 9 · 点赞 3 · 书签 0