子智能体

1.上下文窗口的困境

  • 如何防止不同任务之间互相干扰
  • 把任务委派给SubAgents（子智能体）

2 子智能体的本质

子智能体的定义简明清晰：它是一个具备独立上下文窗口、受限工具权限及明确任务范围的Claude实例。主智能体按需启动子智能体并传递任务描述；子智能体在其独立的上下文空间内执行任务，最后仅向主智能体返回结论，而非过程中的所有细节。

1.隔离
子智能体拥有独立的上下文窗口，其读取的文件内容、命令执行输出及中间推理过程，均严格保留在自身的上下文空间内，绝不回流至主对话。

2.约束
用户可以为每个子智能体配置严格的工具权限白名单。

3.复用
子智能体以Markdown格式定义，支持团队共享及项目迁移。

在此纯净的上下文中，子进程独立执行文件读取、命令运行及结果分析等操作；任务完成后，仅将执行结果的摘要回传至主进程。主对话最终接收到的是一段简洁的结论文本，而子智能体内部所有的中间交互过程，均随着子进程的终止而彻底释放。

3 子智能体的定义与配置

典型的子智能体目录结构如下。

点击查看代码 
your-project/
└── .claude/
└── agents/
├── code-reviewer.md ← 代码审查子智能体
├── test-runner.md ← 测试运行子智能体
├── log-analyzer.md ← 日志分析子智能体
└── bug-locator.md ← bug定位子智能体
  • YAML前置元数据定义了子智能体“是什么”：明确其身份标识、能力边界（如工具权限白名单）及运行配置参数。
  • Markdown正文指令规定了子智能体“怎么做”：详述具体的执行工作流、标准化的输出格式以及所需的专业领域知识。

下面是一个完整的代码审查子智能体定义示例

点击查看代码 
---
name: code-reviewer
description: |
  审查代码质量、安全漏洞和性能问题的专家。
  当用户要求代码审查、安全审计或质量评估时使用。
allowed-tools:
  - Read
  - Grep
  - Glob
model: sonnet
permissionMode: plan
---

你是一名资深的代码审查专家，拥有10年以上的工程经验。

## 审查维度

### 安全性
- 检查硬编码凭证（如 API Key、密码、Token）
- 检查 SQL 注入、XSS、CSRF 等安全漏洞
- 检查输入验证的完整性
- 检查敏感数据的处理方式（如是否加密、是否输出日志）

### 代码质量
- 函数是否遵循单一职责原则
- 命名是否清晰、一致
- 是否存在重复代码（如违反 DRY 原则）
- 错误处理是否恰当（如不吞异常、不使用空的 catch 块）

### 性能
- 是否有不必要的循环嵌套（O(n²) 以上的复杂度）
- 数据结构选择是否合理
- 数据库查询是否存在 N+1 问题
- 是否有未关闭的资源（如文件句柄、数据库连接）

## 输出格式

请严格按照以下格式输出审查结果：

### 审查摘要
[一段话总结整体代码质量，包括亮点和主要问题]

### 发现的问题
- **[严重/主要/次要]** 问题描述 — `file_path:line_number`

### 改进建议
[按优先级排列的具体改进建议]

再来看一个执行型子智能体的示例——测试运行器。

点击查看代码 
---
name: test-runner
description: |
  运行项目测试套件并分析测试结果。
  当用户要求运行测试、检查测试覆盖率或分析测试失败原因时使用。
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: haiku
---

你是一名测试执行专家。你的核心价值是从海量测试输出中提炼关键信息，为主对话提供精准的测试摘要。

## 执行流程

1. 确认项目的测试命令（查阅 package.json 或 CLAUDE.md）
2. 运行测试套件
3. 分析输出结果，区分通过和失败的测试用例
4. 针对失败的测试，定位具体失败原因

## 输出格式（严格遵守）

### 测试摘要

- 总计：X 个测试
- 通过：X 个
- 失败：X 个
- 跳过：X 个

### 失败详情（仅列出失败的测试）

- test_name: 失败原因（用一句话描述） at file_path:line_number

### 建议

[如果存在明显的失败模式，请给出修复方向]

> **注：** 输出中严禁包含完整的测试日志，仅需要输出上述格式的摘要信息。
  • 子智能体定义完成后，主要有两种使用方式。

自动委派：用户只需要向Claude提出常规请求，它会根据任务性质自动判断是否需要将工作委派给特定的子智能体。
显式请求：用户可以直接指示Claude调用某个具体的子智能体来完成任务。

点击查看代码 
用户：帮我审查src/payment/目录下的代码变更。
Claude：好的，我将把审查任务委派给“代码审查专家”。
[启动子智能体：code-reviewer]
...
审查完毕。发现2个问题。
1. [严重] src/payment/processor.ts:45存在SQL注入风险。
2. [次要] src/payment/validator.ts:23缺少边界值校验。

4 5种子智能体模式

4.1 只读型：安全的观察者
只读型是最基础且最安全的子智能体模式，其核心特征可概括为只读不写。

4.2 执行型：高噪声任务处理器
4.3 并行型：多专家工作流
4.4 流水线型：串行处理链
以下是一个bug修复流水线定义示例。

点击查看代码 
<!-- .claude/agents/bug-locator.md -->
---
name: bug-locator
description: 定位产生 bug 的根本原因
tools:
  - Read
  - Grep
  - Glob
permissionMode: plan
---

你是一名 bug 定位专家，任务是找出产生 bug 的根本原因。

## 定位流程

1. **理解症状**：分析错误信息和复现步骤
2. **搜索相关代码**：通过关键词和文件模式锁定可疑区域
3. **追溯调用链**：从错误点向上追溯至根本原因
4. **确认根本原因**：明确指出导致问题的具体代码行

## 输出格式（下游阶段依赖此格式，请严格遵守）

- **根本原因文件**：[file_path:line_number]
- **问题描述**：[一句话概述根本原因]
- **调用链**：[从入口到出错点的完整路径]
- **修复方向**：[简要的修复思路]
点击查看代码 
<!-- .claude/agents/bug-fixer.md -->
---
name: bug-fixer
description: 基于定位结果修复 bug
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash
---

你是一名 bug 修复专家，你将接收 bug-locator 输出的定位结论，并据此实施修复。

## 修复原则

1. **最小改动**：仅修改必要代码，避免无关重构
2. **不引入新问题**：确保修复不会破坏现有功能
3. **风格一致**：遵循项目现有的代码风格
4. **防御性代码**：添加必要的防护措施，防止同类问题复发

## 输出格式

- **修改的文件**：[file_path_1, file_path_2, ...]
- **每处修改的原因**：[逐一说明]
- **潜在副作用**：[如果有，请详细说明]
- **建议的测试命令**：[用于验证修复的具体命令]
点击查看代码 
<!-- .claude/agents/bug-verify.md -->
---
name: bug-verify
description: 验证 bug 修复是否有效
tools:
  - Read
  - Grep
  - Glob
  - Bash
permissionMode: plan
---

你是一名 bug 验证专家。你将收到 bug-fixer 的修复结论，基于此运行测试验证修复是否有效。

## 验证流程

1. **阅读修复报告**：了解本次修复涉及的文件变更及核心修复思路
2. **运行建议的测试命令**：运行 bug-fixer 提供的具体验证命令
3. **进行回归测试**：确保本次修复未对其他既有功能造成副作用
4. **实施边界检查**：针对已识别的根本原因，构造边界条件下的输入数据，验证防御性代码是否按预期生效

## 输出格式（下游阶段依赖此格式，请严格遵守）

- **验证结果**：[通过 / 未通过]
- **测试执行记录**：[列出已执行的具体命令及其对应的执行结果]
- **回归影响**：[说明本次修复是否导致其他测试用例失败]
- **遗留风险**：[如有，请明确指出；如无，可填写“无”]
点击查看代码 
<!-- .claude/agents/bug-report.md -->
---
name: bug-report
description: 分析修复的影响范围并生成报告
tools:
  - Read
  - Grep
  - Glob
permissionMode: plan
---

你是一名 bug 影响分析专家。请基于接收到的前三阶段完整结论，撰写一份结构化的修复报告。

## 分析流程

1. **回溯根本原因**：依据 bug-locator 的结论，提取根本原因
2. **审查修复**：结合 bug-fixer 的结论，明确代码改动的具体范围
3. **确认验证**：参考 bug-verify 的结论，核实修复的最终状态
4. **评估影响**：深入分析该 bug 可能波及的其他模块及用户场景

## 输出格式

- **Bug 摘要**：[一句话精准概括]
- **根本原因**：[文件路径 + 具体原因]
- **修复方案**：[改动要点摘要]
- **验证状态**：[通过 / 未通过]
- **影响范围**：[涉及的模块、API 及用户场景]
- **后续建议**：[是否需要通知下游团队、更新技术文档等]

4.5 团队型：自组织协作机制

  • 在前4种模式中，子智能体仅在任务执行期间活跃，任务完成后即终止，呈现出“一次性”的特征；
  • 而在团队型模式中，子智能体具有长期存续性，它们如同真实团队一般，能够持续协作、实时通信并自主分工。

一个Agent Team由3个核心元素组成（见图4-5）。

  • Team Lead（团队负责人）：承担任务分解、资源调度及进度跟踪的职责，其角色类似于项目经理。
  • Teammate（团队成员）：由具有不同专业特长的子智能体组成，它们各自负责特定的功能模块。
  • 共享基础设施：包括两个关键机制。Task List（任务列表）确保所有成员能实时掌握整体进度与个人待办事项；Mailbox（邮箱）则支持成员间的异步通信（例如，前端开发人员可通过该机制向后端开发人员确认API接口规范）。

团队型子智能体适用于4种典型的协作模式。

  • 竞争假设模式：面对难以定论的复杂问题（例如，性能瓶颈究竟源于数据库查询还是网络I/O），可以派遣多个子智能体基于不同的假设方向并行调查。最终，由Team Lead对比多份调查报告，择优选取证据最充分的结论。
  • 并行审查模式：针对同一份代码变更，可同时安排安全审查与功能审查。两位审查者独立作业、互不干扰，最后合并审查意见。该模式不仅比串行审查更高效，而且多视角的独立性也能显著提升审查质量。
  • 模块归属模式：在大型重构任务中，将代码库按模块划分并分配给不同的团队成员。例如，前端子智能体负责UI（User Interface，用户界面）组件重构，后端子智能体负责API层重构，数据层子智能体负责数据库迁移。各子智能体深耕其负责的模块，并通过Mailbox协调跨模块的接口变更。
  • 方案审批模式：由一个子智能体提出重构方案，另一个子智能体则扮演“魔鬼代言人”角色，专门提出挑战与质疑。Team Lead依据双方的论证做出最终决策。这种对抗性设计能有效规避方案中的思维盲点。

5 子智能体与Skills的协作

方向A：子智能体预加载Skill（子智能体包含Skill）
在此模式下，子智能体的定义文件通过skills字段，在启动阶段预加载一个或多个Skill作为领域知识库。

  • 角色定位：子智能体是执行者，而Skill则是其手中的“操作手册”。
  • 适用场景：流水线中需要特定领域知识的角色。例如，bug-fixer需要加载安全编码规范，doc-generator则需要加载文档生成流程。

方向B：Skill派生子智能体（Skill包含子智能体）
在此模式下，Skill通过配置context: fork，在被触发时自动创建一个隔离的子智能体来执行任务，确保中间过程不污染主对话上下文。

  • 角色定位：Skill是调度者，子智能体是执行实例。
  • 适用场景：深度代码分析、批量文档生成等需要严格隔离且一次性完成的重型任务。

这两种模式的核心差异在于System Prompt的控制权归属。

  • 方向A：子智能体的定义文件（.md正文）构成System Prompt，而Skill的全量内容被作为领域知识上下文注入。
  • 方向B：由agent字段指定的Agent类型提供System Prompt，而SKILL.md的内容则作为具体的任务指令传入。

接下来我们通过两个实例深入解析方向A。首先是改进版的bug-fixer。

点击查看代码 
<!-- .claude/agents/bug-fixer.md -->
---
name: bug-fixer
description: 基于定位结果修复 bug，遵循团队安全编码规范
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash
skills:
  - secure-coding # 预加载安全编码 Skill
---

你是一名 bug 修复专家。你将接受来自 bug-locator 的定位结论，并据此执行修复。

在修复过程中，必须严格遵循 `secure-coding` Skill 中定义的安全编码规范。请特别注意以下关键点：**空值检查**、**输入验证**以及**错误处理模式**。

## 修复原则

1. **最小改动**：仅修改必要的代码，避免无关的重构
2. **零副作用**：确保修复不会破坏既有功能
3. **规范遵从**：严格遵循 Skill 中定义的安全编码规范
4. **防御性编程**：添加防御性代码，防止同类问题复发

## 输出格式

- **修改的文件**：[file_path_1, file_path_2, ...]
- **修改原因**：[逐一说明每处修改的理由]
- **安全检查项**：[列出 Skill 清单中已确认通过的检查项]
- **建议的测试命令**：[用于验证修复的具体命令]

对应的Skill定义如下。

点击查看代码 
<!-- .claude/skills/secure-coding/SKILL.md --> ---
name: secure-coding description: Secure coding checklist for bug fixes and new features.
Use when fixing bugs, writing new code, or reviewing security aspects.
user-invocable: false ---
# 安全编码规范
## 空值防御
- 输入校验：所有外部输入必须进行非空检查
- 安全访问：优先使用可选链操作符（?.）访问嵌套属性，严禁使用非空断言（!.）
- 数据判空：数据库查询结果在业务逻辑使用前，必须显式进行判空处理
## 错误处理
- 统一异常：业务逻辑异常必须使用项目统一的AppError类，禁止直接抛出原生异常或字符串
- 拒绝静默失败：严禁空的catch代码块，捕获异常后，至少需要记录错误日志或进行重试处理
- 超时控制：所有异步操作必须配置明确的超时时间
## 日志规范
- 专用接口：生产环境严禁使用console.log()。必须使用项目封装的logger对象（如logger.error()）
- 信息完整：错误日志必须包含唯一的error code以及完整的堆栈跟踪（stack trace）
- 数据脱敏：严禁在日志中输出任何敏感信息（包括但不限于密码、API Token）

再来看一个跨领域的实例——API文档生成子智能体，其通过预加载“文档生成Skill”来强化专业能力。

点击查看代码 
<!-- .claude/agents/api-doc-generator.md --> ---
name: api-doc-generator 
description: Generate API documentation by scanning route files.
tools:
- Read - Grep - Glob - Write - Bash skills:
- api-generating ← 预加载Skill以注入领域知识
---
You are an API documentation specialist.
Follow the api-generating Skill for workflow and templates.

具体分工如下。
子智能体（.md配置文件）负责战略层面。

  • Who（身份）：确立角色定位，如“你是一名漏洞修复专家”或“你是一名API文档专家”。
  • What（任务）：明确核心目标，如“修复漏洞”或“生成API文档”。
  • Where（范围）：界定工作边界，如“写入docs/api/目录”。
  • Output（交付）：规定产出形式，如“返回包含修复详情的摘要”或“统计路由数量”。

Skill（SKILL.md及附属文件）负责战术执行。

  • How（流程）：细化操作步骤，如“第一步：运行detect-routes.py→第二步：分析结果”。
  • With What（工具）：指定依赖资源，如脚本scripts/detect-routes.py、模板templates/api-doc.md。
  • By What Standard（规范）：设定执行准则，如“检查认证中间件并标记为锁”。
  • Quality（质量）：明确验收标准，如“所有路由均已归档，Schema与代码严格一致”。

这种分离机制赋予了系统强大的复用能力。

  • 再看方向B——Skill派生子智能体。通过在SKILL.md的YAML前置元数据中设置context: fork，Skill在被触发时会自动创建一个隔离的子智能体来执行任务。这种机制确保了中间过程不会污染主对话的上下文环境。
点击查看代码 
---
name: codebase-health-check
description: Perform comprehensive code health analysis
context:
  fork: agent
  allowed-tools:
    - Read
    - Grep
    - Glob
---

Analyze the codebase at $ARGUMENTS and produce a health report.

方向A：角色驱动（子智能体是主角）。

  • 结论：当需要维持角色状态、进行多轮交互或复杂协作时，选择方向A。

方向B：知识/流程驱动（Skill是主角）。

  • 结论：当任务是单次性的，需要严格隔离上下文，或者重点在于复用标准化流程时，选择方向B。

6 Token经济学

  • 上下文窗口保护。Claude的上下文窗口容量是有限的。
  • 响应质量提升。纯净的上下文环境能显著提升Claude的聚焦能力。

7 从软件工程看子智能体

1.单一职责原则

  • 职责专一化：code-reviewer仅专注于代码质量审查；test-runner仅负责执行测试用例并收集结果；bug-locator仅致力于定位产生bug根本原因。每个子智能体都如同一个高内聚的独立类，各司其职，互不越界。
  • 声明式职责说明书：每个子智能体的Prompt文件（如code-reviewer.md）实质上就是它的“职责说明书”。
  • 变更隔离与维护性：例如，若需要调整代码审查的严格程度或引入新的安全规范，开发者仅需修改code-reviewer.md这一文件。

2.舱壁模式

  • 故障熔断与边界锁定：如果log-analyzer子智能体在处理海量日志时遭遇异常数据（如死循环、幻觉爆发或格式崩溃），由此产生的“故障”会被严格封锁在子智能体的独立沙箱内。
  • 主系统稳定性保障：由于“舱壁”的存在，子任务的混乱不会污染主对话的上下文环境。
  • 优雅降级：这种设计确保了系统的韧性。
  1. MapReduce模式

4.责任链模式

8 实战注意事项
首先是CLAUDE.md的继承关系。
其次是上下文的“报文传输”模式。
然后是中断恢复机制。
最后是嵌套深度控制。

本章小结

子智能体是Claude Code扩展体系中最具架构意义的特性。如果说CLAUDE.md赋予了Claude记忆能力，Skills赋予了它专业知识，那么子智能体所赋予的则是一种更为根本的能力——分解复杂性的能力。

posted @ 2026-08-03 17:05  不知者buwei  阅读(0)  评论(0)    收藏  举报