第 5 章 · 03 设计三原则与上下文管理

第 5 章 · 03 设计三原则与上下文管理

本节摘要:配置子代理并不难,难的是设计——八个示例代理背后有一套共同的规律。本节提炼出设计三原则:单一职责、描述明确、工具权限最小化;并讲清楚 System Prompt 怎么写、子上下文开多大、什么时候该用子代理、插件分发时怎么收敛权限。读完本节,你就能为自己的项目定制子代理。

学习目标

阅读完本节,你应当能够:

1. 背出设计三原则,并解释每条原则背后的动机。
2. 写出合格的 description 与 System Prompt(具体、简洁、只留执行所需信息)。
3. 判断一个任务该不该交给子代理(可拆分/需隔离/需分工/需并行)。
4. 说出插件分发子代理时的权限边界与收敛方法。

一、原则一:单一职责

回看第 2 节的八个示例代理,每个代理只回答一个问题:code-reviewer 只做代码审查,debugger 只做根因分析,data-scientist 只做数据分析——没有一个代理是"万能助手"。

单一职责的原则来自委派机制本身:主 agent 依据 description 判断"这件事该交给谁",如果某个代理的职责模糊(比如"帮助用户处理各种任务"),主 agent 就永远无法判断何时调用它,结果要么永远不被调用,要么被错误调用。职责越聚焦,description 越好写,委派越准确。

实践上的判断标准:如果一个代理的 System Prompt 里出现"同时也要""此外还可以"这类词,说明职责已经膨胀,应该拆分成两个代理。参考第 2 节的对比:审查类三个代理(code-reviewer / clean-code-reviewer / secure-reviewer)关注点完全不同——通用规范、Clean Code 风格、安全漏洞,各自独立,这正是"单一职责"的教科书式拆法。

二、原则二:描述明确

description 是子代理的简历,主 agent 只靠它决定何时委派。八个示例代理的 description 都遵循同一个句式:"当用户想要 X 时使用"——直接用触发场景描述,而不是描述能力。

合格 description 的三个要点:

1. 以触发条件开头:"当……时使用",让主 agent 一读就知道匹配规则。
2. 说清任务类型与产出:是审查、实现、调试还是写文档;产出是审查报告、代码还是测试用例。
3. 避免能力描述:写"擅长 Python"没有意义,要写"当用户需要调试 Python 异步代码时使用"。

反过来,一个不合格的 description 是"负责审查代码质量、协助测试、帮助写文档、提供优化建议"——四个职责叠加,主 agent 面对具体任务时无法判断该不该调它。

三、原则三:工具权限最小化

工具集是子代理的行为边界:给什么工具,它就只能做什么事。八个示例代理的规律非常清晰——工具集 = 职责边界:

• 审查型代理:code-reviewer 只给 Read + Grep(不能写文件,只能看);secure-reviewer 更进一步,只读且聚焦安全相关文件。审查的本质是"只读判断",给它们编辑工具反而会让审查变成修改,越权且危险。
• 实现型代理:implementation-agent 给 Read + Edit + Write + Bash,因为它要真正改代码、跑测试;debugger 额外给 Bash(运行复现问题),不给 Edit——调试阶段不允许乱改。
• 专用型代理:data-scientist 不碰文件系统(只做分析,不给文件工具),documentation-writer 给全部写工具。

最小权限的落点:审查型只读、实现型适度开放、高风险动作保持审批。如果你的代理需要执行 Bash,务必想清楚它凭什么需要;如果只是查信息,给 Read 就够。

四、System Prompt:具体,且不要长

System Prompt 是子代理的"岗位说明书",八份示例的 Prompt 都在 50~150 行之间,长的原因是包含任务步骤与输出格式模板,而不是空泛的价值观。写 Prompt 的三条经验:

1. 包含执行所需的一切:任务步骤、输出格式、验收标准、常见坑。子代理是全新上下文,没有和你对话的历史,任何你"默认它知道"的东西都要写进 Prompt。
2. 不要写废话:不要重复"你是一个优秀的工程师"之类的自我定位,不要贴大段通用方法论,不要写与任务无关的背景。Prompt 每多一行,子代理的注意力就被稀释一分。
3. 用步骤清单代替散文:比如 code-reviewer 的六维审查(正确性/可维护性/性能/安全性/测试覆盖/风格)与 Severity 输出格式,直接可执行;散文式的"请全面审查代码"则无法执行。

一个有用的自检:删掉 Prompt 中任何一句话,如果子代理的输出不受影响,这句话就不该存在。

五、上下文管理:子上下文尽量小

子代理的价值来自上下文隔离,但隔离不是免费的——子上下文开得越大,两个代价越明显:

1. 速度:子代理启动时要把上下文交给模型,上下文越大,首响应越慢。
2. 准确性:上下文越长,模型对其中关键指令的遵循度越低(指令淹没效应),任务越容易被"带偏"。

所以上下文管理的原则是:只给任务必需的背景。实现手段包括:Prompt 里只写任务相关的约束,不复制整个项目背景;需要参考代码时让子代理自己用 Read/Grep 去取,而不是把大段代码粘进 Prompt;明确的输入输出约定(比如"输入:文件路径列表;输出:按模板填写的报告"),避免子代理自己猜测范围。

六、使用时机:四种该用子代理的情形

判断"这个任务要不要交给子代理",四种情形应该用:

1. 任务可拆分:一个大任务能拆成多个互不依赖的独立子任务(比如同时审查多个模块)。
2. 需要隔离上下文:子任务要接触大量文件,会污染主上下文(比如探索一个大型代码库);或者子任务危险,不希望它影响主任务状态。
3. 需要角色分工:子任务需要特定角色视角(安全审查、性能分析),角色越单一,子代理的 Prompt 越聚焦。
4. 需要并行:多个独立子任务同时进行,主 agent 可以并行委派多个子代理,整体耗时接近最慢的那一个。

反过来,不需要用子代理的情形:任务简单(直接用主 agent 做)、子任务之间强耦合(需要反复交换中间结果)、或任务本身就在主上下文中(隔离没有收益)。

七、插件分发与权限收敛

子代理不只能放在项目/用户目录,还能随插件分发(第 8 章详述)。插件分发时,权限与边界更需注意:

• 插件子代理被沙箱限制:不能配置 hooks、不能带 mcpServers、不能修改 permissionMode——这是官方硬性限制,设计插件代理时不要规划这些能力。
• 插件代理的 tools 字段只能使用基础工具集(Read/Edit/Write/Bash/Grep/Glob 等内置工具),不能引用插件自己声明的 MCP 服务器。
• 分发时务必收敛工具权限:审查类插件代理(如 pr-review 插件里的 security-reviewer)一律只读,避免用户安装插件后被悄悄拿到写权限。

另外,你还可以通过 spawn 名单限制控制子代理的可见范围:在配置中列出允许使用的子代理列表(以及各自的 tools 白名单),未被列出的代理即使存在也不会被自动委派——这是多团队共享项目时防止"代理爆炸"的手段。

小结

设计子代理的本质是设计边界:单一职责让委派准确,明确的 description 让主 agent 知道何时调用,最小化工具集让代理只能做它该做的事。System Prompt 要具体而克制,子上下文要尽量小,只在可拆分、需隔离、需分工、需并行时启用。审查型代理只读、实现型适度开放、插件分发收敛权限——记住这些规律,八个示例代理就能变成你自己的代理工厂。

下一节预告:子代理是"人的分工",下一章我们引入"系统与工具的互联"——第 6 章 MCP 扩展,让 Claude Code 接上外部世界。