Claude Code 子代理深度解析：我之前的用法全错了，这才是正确姿势！ (2026最新)

type

Post

status

Published

date

Oct 15, 2025

slug

claude-code-2026-1vrfo4

summary

📌 来自：faafospecialist.substack.com (Substack) | 💡 别让 AI 子代理直接写代码，让他们当你的“情报收集员”。本文深入探讨了 Claude Code 中 Subagents（子代理）的进阶用法，纠正了开发者常犯的“让子代理直接执行任务”的误区。作者引入了“上下文工程”的概念，解释了为何长文本会导致 Context Rot（上下文腐烂），并分享了如何利用 Markdown 文件作为外部存储、通过“探索-规划-执行”三步法，让 AI 团队在处理复杂任务时不再陷入无限循环。 | 🔑 关键词：Substack、faafospecialist.substack.com、FA&FO | 🤖 由Gemini 3 Flash (Google API)分析生成

Claude Code 子代理（Subagents）概览

这是关于 Claude Code 系列文章的第四篇。原本计划写关于 Commands（命令）的内容，但我最近发现自己在 Subagents（子代理）的使用上犯了不少错误，所以决定先分享这些避坑指南。

如何创建一个 Subagent（子代理）

使用 Claude Code（简称 CC）的 `/agents` 命令可以快速创建一个子代理，然后打开生成的 Markdown 文件根据你的喜好进行自定义。

输入 `/agents` 打开子代理界面。

选择 "Create New Agent"（创建新代理）。

选择项目级别或用户级别。

理解“Delegation”（授权/委派）

默认情况下，Claude Code 本身是 Main Agent（主代理），它会执行所有操作。根据 Claude 的官方文档，创建子代理后，CC 会在需要时“智能地”自动召唤相关代理并委派任务。

但现实是，它太“智能”了，以至于很少召唤子代理，主代理通常会觉得“这很简单，我自己来就行！”。因此，为了更有效地召唤子代理，我们有两种方法：

**自动方式（比默认更主动）： ** 在 `CLAUDE.md` 文件中添加指令，提醒 CC 它手下有一支军队。例如：

“在执行过程中，请根据专业领域将任务委派给以下子代理：

使用 `planner-researcher` 代理规划执行方案。

使用 `database-admin` 代理运行测试并分析报告。

使用 `tester` 代理运行测试。

使用 `debugger` 代理收集日志。

使用 `code-reviewer` 代理评审代码。 ”

**手动方式： ** 直接在 Prompt（提示词）中要求使用某个代理，或使用特定命令。

接下来，需要了解子代理召唤的两种形式：

**Chaining（链式）： ** 复杂的 Workflow（工作流）。例如：先让代码分析代理找性能问题，再让优化代理去修复。

**Parallel（并行）： ** 竞争性方案。例如：同时部署两个代理，一个负责渐进式现代化方案，另一个负责全栈重构方案。

注意：并行执行容易产生冲突，建议将其配置到特定命令中触发。

每个子代理都拥有：

**独立的上下文窗口： ** 不受主对话影响。

**可定制的系统提示词： ** 专门针对特定角色训练。

**独立的工具访问权限： ** 仅允许使用必要的工具。

**深度专业知识： ** 100% 专注于领域特长。

子代理带来的好处

**Context Preservation（上下文保留）： ** 无需在每次任务切换时从头解释，每个代理维持自己的上下文，主对话保持简洁。

**Specialized Expertise（专业分工）： ** 专门负责安全的代理在审计代码时，成功率远高于通用 AI。

**可重用与团队共享： ** 一次创建，永久使用。

**并行处理： ** 缩短分析、测试、评审的线性等待时间。

深度复盘：为什么你的 AI 团队有时会失效？

你是否遇到过这种情况：拥有一支看似全能的 AI 代理团队，但使用时却时灵时不灵？有时它们消耗 Token（代币）的速度极快，却给出意外的结果，或者陷入修复 Bug 的死循环？

我前几天就遇到了，我甚至觉得子代理没什么用，只会浪费钱。直到我深入研究后才发现，Context Management（上下文管理） 才是关键！

理解多代理系统的上下文窗口

在与 AI 协作时，Context Window（上下文窗口）包含了一切：用户消息、AI 回复、工具调用及其结果。这个“盒子”是有极限的。当 CC 活跃时，窗口会迅速填满。

例如：输入 2k + 思考 32k + 工具调用 40k... 几个回合下来，Token 消耗就能达到 148k 甚至更多。一旦接近上限，输出质量就会大幅下降。

上下文工程：将文件系统作为内存

我参考了 Manus 团队关于 Context Engineering（上下文工程）的研究。他们使用文件系统来管理上下文，我将其应用到了 Claude Code 中。

在 `planner-researcher` 代理的系统提示词中，我增加了指令：将执行计划和待办事项记录在 `./plans` 文件夹下的 Markdown 文件中，并在报告中附上文件路径。这样，主代理和其他代理在需要时只需读取该文件，而不需要将全部内容塞进主上下文窗口，节省了大量 Token。

Context Rot（上下文腐烂）

Chroma 团队的一项研究揭示了 Context Rot 现象：即使是简单任务，随着输入长度增加，LLM（大语言模型）的性能也会下降。

研究发现：

**问题相似度： ** 当问题与所需信息的语义相似度降低时，性能下降更快。

**干扰项： ** 即使只有一个干扰信息，性能也会下降；如果有四个干扰项，性能会“断崖式下跌”。有趣的是，GPT 在困惑时倾向于胡编（幻觉），而 Claude 则倾向于拒绝回答。

**结构化陷阱： ** 逻辑清晰的长文本反而比随机打乱的文本更难检索信息，因为模型会陷入文本的“思维流”中而忽略特定细节。

这说明增加上下文窗口长度不是终极方案，如何选择、组织和呈现信息才是决定性因素。

我对子代理的误解

Claude Code 刚发布子代理功能时，很多人（包括我）觉得它比主代理慢、费 Token，且效果一般。这是因为我们误解了它的设计初衷。

为什么需要子代理？

主代理在读取文件时会“吞噬”数千 Token。

**过去： ** 主代理读取大量文件 -> 占据 80% 上下文 -> 触发压缩对话 -> 丢失细节 -> 性能骤降。

**现在： ** 子代理负责研究任务 -> 独立工作 -> 仅向主对话返回简短摘要 -> 主代理接收的是精炼信息而非原始数据。

常见错误：让子代理去执行（Implementation）

我最初以为：前端代理写前端，后端代理写后端，主代理只负责调度。

问题在于： 每个子代理只知道自己的任务，对整个项目缺乏全局上下文。修 Bug 时，它们对其他部分发生的事情完全是“盲目”的。

最佳实践：子代理是“情报收集军”

根据 Claude Code 核心工程师 Adam Wolf 的反馈：“子代理最擅长的是寻找信息并提供少量摘要返回给主对话。”

为每个代理配置正确的工具

不要因为懒惰就让所有代理拥有所有工具的权限。这会导致代理“越权”执行冗余任务，污染上下文并浪费 Token。

我重新组织了我的子代理团队：

**Planner (Researcher)： ** 负责理解代码库、搜索文档、制定详细计划（存入 MD 文件）。

**Debugger： ** 分析日志、诊断数据库、提供优化方案。

**Tester： ** 运行测试套件、分析失败日志。

**Database Admin： ** 查询数据库、分析表结构。

**Docs Manager： ** 维护代码规范、更新 PDR（产品开发文档）。

**Code Reviewer： ** 评审质量、安全审计。

关键点： 这些代理都不直接负责“执行代码”！它们只负责为核心代理（Claude Code 本身）收集和提炼信息。

提效流程：探索 - 规划 - 执行

**Explore（探索）： ** 让代理阅读文档、分析结构、总结要点。

**Planning（规划）： ** 使用高阶模型（如 Opus）接收探索报告，制定详细计划，并要求其先汇报计划。

**Execute（执行）： ** 确认计划后，由主代理开始写代码，完成后召唤子代理（如 Tester）进行验证。

绝技：Double Escape（双击 ESC）

在构建好上下文后，连按两次 ESC 键可以 Fork（分叉）对话。打开新终端，使用 `--resume` 标志重新激活 Claude Code。这样你可以同时拥有 5 个共享相同“记忆”的终端窗口！

总结

我之前被一个 API 测试困扰了 3 天，更新了这套子代理策略后，顺利通过了！虽然我可以手动修复，但我更想测试 AI 的极限。

📌 关键收获

对 Grace 的启示

**建立独立站的“SOP 内存”： ** 模仿文中将“文件作为内存”的做法。在你的独立站项目中，建立一个 `./docs` 文件夹，存放 SEO 策略、品牌语调、代码规范等。不要每次都把这些塞进 Prompt，而是让 AI 在需要时去读取特定的 Markdown 文件。

**改变 AI 协作模式： ** 不要直接对 AI 说“帮我写个落地页”，而是先派出一个“调研代理”去分析竞品，再派出一个“规划代理”写框架，最后由你或主代理来执行。这种“情报先行”的策略能极大减少 AI 的幻觉。

**警惕“上下文污染”： ** 在处理复杂的营销方案或长文章翻译时，如果发现 AI 开始胡言乱语，及时使用“双击 ESC”或开启新对话（Resume）的方法，清理掉不必要的干扰信息，只保留核心背景。

一个高效的 AI 系统不在于它能吞下多少信息，而在于它是否知道如何正确处理信息。

👉

想了解更多细节？ 查看原文 →