批量商品分类审核与上下文管理 - 实战 Subagent
本文通过一个真实的商品分类审核场景，详细讲解 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 处理，但很快发现问题：
- 上下文爆炸：5000 个商品 + 分类表 + 审核结果，轻松超出上下文限制
- 串行处理慢：逐个商品判断，效率太低
- 结果混乱：长对话中，Claude 容易 "忘记" 之前的判断标准
Subagent 天然解决这些问题：
| 痛点 | Subagent 方案 |
|---|---|
| 上下文爆炸 | 每个 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}`几个关键设计点：
- tools 精简：只给
Read和Write，不需要Bash等其他工具 - 输入输出分离：通过文件路径传递数据，而不是直接传内容
- 明确输出格式：JSON 结构固定，方便后续脚本处理
- 简洁回复：只回复确认信息，不要长篇大论
第二步：上下文管理 —— 这是关键！
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
经验总结
| 原则 | 说明 |
|---|---|
| 数据不入上下文 | 大量数据通过文件传递，主 Agent 只传路径 |
| 脚本做重活 | 分组、统计、汇总等操作交给 Python 脚本 |
| Subagent 输出到文件 | 不要让 Subagent 返回大量内容 |
| 只关注异常 | 只汇总 "未覆盖" 的商品，忽略正常的 |
| 确认再执行 | 修改重要文件前，先展示建议等待确认 |
Subagent 适用场景
通过这次实战，我总结了 Subagent 的最佳适用场景：
适合用 Subagent
- 大量同质化任务（如本文的批量审核）
- 需要隔离上下文的独立子任务
- 可并行处理的工作
- 需要专业化 prompt 的特定领域任务
不适合用 Subagent
- 简单的一次性任务
- 需要持续对话、多轮迭代的任务
- 强依赖上下文连贯性的任务
结语
Subagent 是 Claude Code 中非常强大的功能，但用好它需要注意上下文管理。核心思路就是：
主 Agent 是调度员，不是搬运工。数据流转靠文件，不靠对话。
希望这篇实战分享对你有帮助。如果你也有类似的大规模数据处理场景，不妨试试 Subagent + 脚本的组合方案。
本文基于 Claude Code 实际使用经验撰写，欢迎交流讨论。
