本文通过一个真实的商品分类审核场景，详细讲解 Claude Code Subagent 的创建、调用，以及大规模数据处理时的上下文管理技巧。

背景

我需要维护一份商品标准化分类体系表。随着业务发展，商品清单不断增加，我需要定期检查：哪些商品还没有被现有分类覆盖？

手上有两个文件：

• goods.txt：商品清单，一行一个商品名，约 5000 个
• 标准化分类体系表.md：现有的分类表，markdown 表格格式

目标很简单：找出所有未被覆盖的商品，并给出分类建议。

解决方案对比

面对这个需求，我尝试了三种方案：

方案 1：直接 Prompt 让 AI 处理

最直接的想法：把 goods.txt 和 标准化分类体系表.md 都丢给 Claude，让它一次性处理。

核心问题：

• 上下文溢出：5000 个商品 + 分类表 + 审核结果，轻松超出上下文限制
• 输出不稳定：AI 处理到第 3000 个商品时，可能 "忘记" 前面的判断标准
• 无法并行：只能串行处理，5000 个商品要等很久
• 结果难以解析：AI 输出格式不一致，后续脚本难以处理

方案 2：使用 Skills

把审核逻辑封装成一个 Skill，让主 Agent 调用。

改进点：

• Skill 可以复用，审核逻辑标准化
• 可以分批处理，降低单次上下文压力

依然存在的问题：

• 上下文累积：每批的输入输出仍然留在主对话中
• 无法真正隔离：所有 Skill 调用共享主 Agent 的上下文
• 并发受限：Skill 仍是串行执行，无法并行加速

方案 3：使用 Subagent（本文方案）

为审核任务创建独立的 Subagent，每个 Subagent 处理一批商品。

核心优势：

• 上下文隔离：每个 Subagent 拥有独立的上下文，互不干扰
• 可并行处理：多批审核可以同时进行（理论上）
• 输出标准化：Subagent 严格按照定义的 JSON 格式输出
• 主 Agent 轻量：主 Agent 只做调度，不接触数据内容

什么是 Subagent？

简单来说，Subagent 就是一个可以被主 Agent 调用的 "专家助手"。

你可以把它理解为：

• 函数：定义好输入输出，主 Agent 调用时传参
• 独立进程：拥有自己的上下文，不污染主 Agent
• 专业顾问：每个 Subagent 可以有自己的专业领域和工具集

不过，不要太纠结概念。接下来通过实战，你会直观理解 Subagent 是怎么工作的。

为什么选择 Subagent？

最初我想直接让 Claude Code 处理，但很快发现问题：

1. 上下文爆炸：5000 个商品 + 分类表 + 审核结果，轻松超出上下文限制
2. 串行处理慢：逐个商品判断，效率太低
3. 结果混乱：长对话中，Claude 容易 "忘记" 之前的判断标准

Subagent 天然解决这些问题：

实战开始

第一步：设计 Subagent

在 .claude/agents/ 目录下创建 category-reviewer.md：

---
name: category-reviewer
description: 商品分类覆盖审核专家。当需要批量检查商品是否被现有分类表覆盖时使用。
tools: Read, Write
model: sonnet

---

你是商品分类覆盖审核专家。

## 输入说明
调用时会提供：
- batch_id: 批次编号

- input_file: 商品列表文件路径
- output_file: 结果输出文件路径



## 执行步骤

1. 使用 Read 读取 input_file，获取商品列表
2. 使用 Read 读取 `doc/goodscategoryreview/标准化分类体系表.md` 3. 逐一判断每个商品的分类覆盖情况
4. 将结果 JSON 写入 output_file

5. 回复确认信息



## 判断标准

- **covered**：商品名称能够明确归入现有某个分类

- **uncovered**：商品无法归入任何现有分类



## 输出格式

写入 output_file 的 JSON：

{
  "batch_id": "xxx",

  "results": [

    {"name": "商品A", "status": "covered", "matched_category": "匹配的分类"},
{"name": "商品B", "status": "uncovered", "reason": "原因", "suggested_category": "建议分类"}

  ]

} ## 注意事项 - 每个商品都必须有一条记录，不要遗漏
- status 只能是 "covered" 或 "uncovered"
- 相似商品的 suggested_category 保持一致



## 完成回复

只需回复：`✓ {batch_id} 完成，已写入 {output_file}`

几个关键设计点：

1. tools 精简：只给 Read 和 Write，不需要 Bash 等其他工具
2. 输入输出分离：通过文件路径传递数据，而不是直接传内容
3. 明确输出格式：JSON 结构固定，方便后续脚本处理
4. 简洁回复：只回复确认信息，不要长篇大论

第二步：上下文管理 —— 这是关键！

5000 个商品，如果直接让主 Agent 读取并分组，商品列表就会进入上下文。167 个批次的调用记录，又会持续膨胀上下文。

错误做法

1. 读取 goods.txt（5000 商品进入上下文）
2. 分组并逐批调用 subagent（调用记录堆积）

预估上下文：~150,000 字符，非常臃肿。

正确做法

核心原则：主 Agent 只做调度，不接触数据内容

1. 用脚本预处理数据（主 Agent 不读商品内容）
2. 主 Agent 只传递文件路径给 Subagent
3. 用脚本汇总结果（主 Agent 不读 batch 文件）

预估上下文：~20,000 字符，精简高效。

第三步：完整的主流程 Prompt

这是我最终优化后的 Prompt：

我需要找出商品清单中所有未被现有分类覆盖的商品。

## 文件路径
- 商品清单：doc/goodscategoryreview/goods.txt
- 分类表：doc/goodscategoryreview/标准化分类体系表.md
- 审核结果目录：doc/goodscategoryreview/review_output/

## 任务流程

### 第一步：准备工作
编写并执行 Python 脚本 `prepare.py`：
1. 创建 doc/goodscategoryreview/review_output/input/ 目录
2. 读取 goods.txt，按 30 个一批分组
3. 将每批商品写入单独文件：
   - doc/goodscategoryreview/review_output/input/batch_001.txt
   - doc/goodscategoryreview/review_output/input/batch_002.txt
   - ...
4. 输出批次总数到 doc/goodscategoryreview/review_output/batch_count.txt

### 第二步：批量审核
1. 读取 batch_count.txt 获取批次总数 N
2. 循环 i 从 1 到 N，对每个批次调用 category-reviewer subagent：

使用 category-reviewer subagent 审核：

batch_id: batch_{i:03d}
input_file: doc/goodscategoryreview/review_output/input/batch_{i:03d}.txt
output_file: doc/goodscategoryreview/review_output/batch_{i:03d}.json

注意：
- 不要读取 input 文件内容，只传递文件路径
- 不要读取 output 文件内容，只确认完成

### 第三步：汇总统计
编写并执行 Python 脚本 `summarize.py`：
1. 读取所有 batch_*.json
2. 只提取 status = "uncovered" 的记录
3. 按 suggested_category 分组
4. 统计总数、未覆盖数、覆盖率
5. 保存到 summary.json

### 第四步：生成报告
读取 summary.json（精简数据），生成 report.md：
- 审核概览
- 未覆盖商品清单（按建议分类分组）
- 分类调整建议

### 第五步：等待确认
展示对 标准化分类体系表.md 的修改建议，等待我确认后再执行修改。

## 关键约束
- 主对话中绝不读取商品列表原文
- 主对话中绝不读取 batch 输入/输出文件内容
- 所有数据处理通过 Python 脚本完成
- 只关注未覆盖的商品

请开始执行。

第四步：执行过程

执行后，Claude Code 会：

1. 生成预处理脚本 prepare.py

2. 逐批调用 Subagent

每个 Subagent 独立执行，主 Agent 只收到简短确认：

✓ batch_001 完成，已写入 doc/goodscategoryreview/review_output/batch_001.json
✓ batch_002 完成，已写入 doc/goodscategoryreview/review_output/batch_002.json
...

3. 生成汇总脚本 summarize.py

4. 输出最终报告

最终文件结构

doc/goodscategoryreview/
├── goods.txt                      # 原始商品清单
├── 标准化分类体系表.md              # 分类表
└── review_output/
    ├── input/
    │   ├── batch_001.txt          # 第1批输入
    │   ├── batch_002.txt          # 第2批输入
    │   └── ...
    ├── batch_001.json             # 第1批结果
    ├── batch_002.json             # 第2批结果
    ├── ...
    ├── batch_count.txt            # 批次总数
    ├── summary.json               # 汇总统计
    └── report.md                  # 最终报告 

进阶拓展：从 "主副二人组" 到 "多人团队"

本文的实战方案中，只有审核环节用了 Subagent，其他步骤（数据准备、汇总统计、报告生成）还是通过 Python 脚本完成的。

其实，我们可以把整个流程的每个环节都交给专门的 Subagent 处理，这样就形成了一个多人协作的 AI 团队：

踩坑与经验总结

踩坑 1：让 AI 直接计数

错误：让 Subagent 输出 “已覆盖数量: 25, 未覆盖数量: 5”

问题：AI 不擅长精确计数，容易出错

正确：让 Subagent 逐条输出每个商品的判断结果，用脚本统计数量

踩坑 2：主 Agent 读取 Subagent 输出

错误：每批完成后，主 Agent 读取 JSON 文件检查结果

问题：167 个批次的 JSON 内容全部进入上下文，直接爆炸

正确：主 Agent 只确认完成，最后用脚本统一汇总

踩坑 3：在调用时传递商品列表内容

错误：

使用 category-reviewer subagent 审核：
products:
商品1
商品2
...（30个商品名）

问题：167 次调用 × 30 个商品名 = 大量内容进入主 Agent 上下文

正确：只传文件路径

使用 category-reviewer subagent 审核：
input_file: xxx/batch_001.txt

经验总结

Subagent 适用场景

通过这次实战，我总结了 Subagent 的最佳适用场景：

适合用 Subagent

• 大量同质化任务（如本文的批量审核）
• 需要隔离上下文的独立子任务
• 可并行处理的工作
• 需要专业化 prompt 的特定领域任务

不适合用 Subagent

• 简单的一次性任务
• 需要持续对话、多轮迭代的任务
• 强依赖上下文连贯性的任务

结语

Subagent 是 Claude Code 中非常强大的功能，但用好它需要注意上下文管理。核心思路就是：

主 Agent 是调度员，不是搬运工。数据流转靠文件，不靠对话。

希望这篇实战分享对你有帮助。如果你也有类似的大规模数据处理场景，不妨试试 Subagent + 脚本的组合方案。

本文基于 Claude Code 实际使用经验撰写，欢迎交流讨论。