清风自叙小筑

Appearance

sub-agents ​

跑测试 → 500 行日志。 搜索代码 → 200 行 grep。 分析错误 → 一堆中间推理过程…… 它们对“当下执行”是必要的，但对“后续决策”是噪声。 （这个时候需要子代理）

什么是子代理？ ​

子代理相当于一个“专职小助手”，带着自己的规则、工具权限、上下文窗口，去完成某一类任务，然后把“结果摘要”带回来 把一个大脑拆成多个岗位角色，每个岗位只做一件事，并且有明确的权限边界。

子代理的核心价值 ​

子代理的工程价值，本质上就是三件事：隔离、约束、复用，下面我们分别说说。

隔离，解决的是上下文污染问题——大量对当前执行有用、但对后续决策毫无价值的日志、搜索结果和中间推理，不应该进入主对话的长期记忆；子代理天然拥有独立上下文，执行完即丢弃，只把结论带回来，让 Claude 记得更少、但记得对。

内置子代理：开箱即用的“好员工” ​

plan grep 等等

子代理配置文件详解 ​

claude-子代理配置

**** 创建一个子代理，是有所有权限的子代理。

permissionMode bypassPermissions

一条关键约束：子代理不能生成子代理

创建agents 子代理 ​

  1. 交互式创建
步骤 1：输入 /agents
步骤 2：选择 "Create new agent"
步骤 3：选择存放位置（User-level 或 Project-level）
步骤 4：选择 "Generate with Claude" 并描述功能
步骤 5：选择需要的工具
步骤 6：选择模型
步骤 7：保存

  1. 手写配置文件，直接创建 .claude/agents/your-agent.md 文件。其优势是更精细的控制，方便版本管理，可以从其他项目复制。

  2. CLI 参数临时创建，通过 --agents 参数，可以在启动 Claude Code 时传入 JSON 格式的子代理定义。这种方式创建的子代理仅在当前会话中存在，不会保存到磁盘。这种方式特别适合CI/CD 自动化时在流水线中临时创建任务专用的子代理。

四种核心设计模式 ​

sub-agents (子代理委派/集中式编排) ​

Sub-Agents的核心设计思想是一个 Supervisor Agent 充当老板，将任务分解后委派给专门的 Sub-Agent。每个 Sub-Agent 解决一个特定的任务。

简单查询：1 个 Agent，3-10 次工具调用
中等研究：3-5 个 SubAgent，各 3+ 次并行工具调用
复杂研究：10+ 个 SubAgent，全面并行执行

Skills （技能/渐进式能力加载） ​

LangChain把Skills也视为一种多智能体模式。其实此时仍然是单个 Agent（或SubAgent），但通过SKILL.md 文件（或类似配置）实现能力的渐进式加载。Agent 一开始只知道技能的名称和描述，当判断需要某个技能时，才加载完整的指令。

这是一种“准多 Agent”方案——用更轻量的 prompt 切换替代完整的 Agent 切换

在 Skills 模式下，系统仍然由单一 Agent 负责全部推理与执行，所有技能共享同一个上下文窗口，因此在上下文隔离能力上相对较弱，但换来的好处是对话状态可以自然连续地保留在同一个 Agent 内部，无需额外的状态协调机制。

alt text

.claude/skills/
├── deploy/
│   └── SKILL.md          # 部署技能的完整指令
├── review-pr/
│   └── SKILL.md          # PR 审查技能的指令
└── database-migration/
    └── SKILL.md          # 数据库迁移技能的指令

Sub-Agent：独立的上下文 → 适合大量信息过滤 Skill：共享的上下文 → 适合需要连贯对话的场景

Handoffs（交接 / 状态驱动的 Agent 切换） ​

Handoffs的核心思想是活跃的 Agent 根据对话状态动态切换。Agent A 完成自己的阶段后，通过调用 handoff() 工具将控制权（和上下文）传递给 Agent B。

alt text

alt text

Handoffs 是一种“工程模式”，不是一个“框架特性”。

系统规则：
你将按照以下阶段顺序工作：
1. 信息收集（intake）
2. 问题诊断（diagnosis）
3. 解决方案（resolution）

当前阶段：intake

规则：
- 只能提问
- 不要给解决方案
- 当信息完整时，明确声明：`进入 diagnosis 阶段`

Router（路由器 / 并行分发与合成） ​

Router 模式的核心在于对输入进行语义拆分与职责分流。系统首先由 Router 对用户请求进行分类和分解，然后将子查询并行分发给各自负责的专业 Agent，最后再将多个结果统一合成为一个对用户友好的响应。 alt text

用户提问：「我们的退货政策是什么？最近的销售数据如何？」

Router 分解：
├── 查询 1：退货政策 → 政策文档 Agent
├── 查询 2：销售数据 → 数据分析 Agent
└── 合成结果 → 统一回答

对比 ​

  1. 单任务请求（如“帮我修改函数支持分页查询”） alt text

  2. 重复请求效率（第二轮相同类型的请求） alt text

  3. 多领域查询（如“对比 Python/JS/Rust 的性能”） alt text

简单任务中，Sub-Agent 模式有额外开销。多轮对话中，有状态模式效率优势明显。而在多领域查询中，上下文隔离的模式（Sub-Agent、Router）在 token 效率上优势显著——节省 40% 以上的 token 成本。

多 Agent 架构中，模型选型的重要性显著高于无节制地增加上下文规模。

多 Agent 系统普遍存在约 15 倍的 token 成本放大效应，因此只适合用于高价值、高复杂度的任务

从 Sub-Agent 到 Multi-Agent 的架构演进路径 ​

你的任务需要多 Agent 吗？
├─ 单一领域、工具 < 5 个、上下文 < 50K tokens
│  └─→ 不需要。用单 Agent + 好的 prompt 即可
│
├─ 单一领域、但工具 > 10 个
│  └─→ 考虑 Skills 模式（渐进式能力加载）
│
├─ 多领域、各领域需要独立上下文
│  └─→ 使用 Sub-Agents 模式
│
├─ 需要多步骤状态流转（如客服工单流程）
│  └─→ 使用 Handoffs 模式
│
└─ 需要跨多个数据源并行查询
   └─→ 使用 Router 模式

我一般上来先做简单Demo，不用什么设计模式，SubAgent和Skills，到了两三个礼拜后，感觉认知过载了，有点吃不消了，我才开始考虑上面的架构决策树。这是我个人习惯，你也可以在项目一开始就开始全局性的考量，根据具体项目性质和任务的复杂度而定，对整体架构进行详细的设计和规划。

模式选择速查表 ​

alt text

这里也给出从单一Agent到复杂智能体系统设计的一系列黄金法则：

1. 从单 Agent 开始 → 只在遇到明确瓶颈时才升级
2. 先加工具，再加 Agent → Tools 是最小的扩展单位
3. 选对模型 > 堆更多 token → 升级模型的效果超过翻倍预算
4. 上下文隔离是核心价值 → 多 Agent 的第一价值不是并行，是隔离
5. Token 成本要求高价值任务 → 不是所有场景都值得多 Agent

Anthropic 多 Agent 研究系统的 90.2% 性能提升证明了这一点——但 15x 的 token 成本也提醒我们：架构选型永远是性能、成本和可控性的三角博弈。

alt text

企业内部技术助手，主要服务研发团队，支持后面这些功能。 查询内部技术文档（设计文档、规范、Wiki） 回答代码相关问题（接口含义、调用方式） 辅助排查线上问题（日志、监控、错误码） 偶尔需要做跨领域分析（比如： “这个接口改动，会影响哪些系统？上线风险如何？”）

创建一个只能看、不能改的代码审查员子代理 ​

alt text

该创建子代理的场景 ​

alt text

alt text

不该创建子代理的场景 ​

  1. 一次性任务：直接在主对话中完成即可。
  2. 简单的 prompt 模板：直接用 Skill 文件，不需要独立上下文和工具隔离
  3. 自动化触发动作：用 Hook，不需要 AI 分析判断。

噪声输出任务。 ​

  1. 理解“信噪比”框架，学会判断哪些任务适合委托给子代理。
  2. 掌握子代理输出格式设计的方法论，而非只学一个固定模板。

信噪比决策框架 ​

alt text

这里有一个经验法则：如果一个命令的输出超过 50 行（行数也还要视具体情况而定），且你只关心其中不到 10 行（也就是不到五分之一）的内容，就应该用子代理。

项目中，绑定数据的是否可以封装为skills 还是封装成子代理

并行流程和流水线编排 ​

场景一：新接手一个大型项目 ​

name 和 description

Your Domain 部分的关注点

Output Format 中的报告结构

同时让 auth-explorer、db-explorer、api-explorer 探索各自模块， 然后汇总给我一个整体架构理解

场景二：修复一个复杂的 bug ​

alt text

Sub-Agents vs Agent Teams：从“任务委托”到“团队协作” ​

我在设计一个 CLI 工具来追踪代码库中的 TODO 注释。
创建一个 agent team 从不同角度探索这个问题：
一个 teammate 负责 UX，一个负责技术架构（用最好的模型），一个扮演审评质疑者（用普通模型）。

alt text

Sub-Agents是快速、廉价的“派出去-带回来”模式，如果只需汇报结果 ，就选 Sub-Agents；Agent Teams是复杂、协作的“组队讨论”模式，如果需要互相讨论、挑战、协调 ，就选 Agent Teams。