本文通过一个真实的商品分类审核场景，详细讲解 Claude Code Subagent 的创建、调用，以及大规模数据处理时的上下文管理技巧。
我需要维护一份商品标准化分类体系表 。随着业务发展，商品清单不断增加，我需要定期检查：哪些商品还没有被现有分类覆盖？
手上有两个文件：
goods.txt：商品清单，一行一个商品名，约 5000 个标准化分类体系表.md：现有的分类表，markdown 表格格式目标很简单：找出所有未被覆盖的商品，并给出分类建议 。
面对这个需求，我尝试了三种方案：
最直接的想法：把 goods.txt 和 标准化分类体系表.md 都丢给 Claude，让它一次性处理。
核心问题：
上下文溢出 ：5000 个商品 + 分类表 + 审核结果，轻松超出上下文限制输出不稳定 ：AI 处理到第 3000 个商品时，可能 "忘记" 前面的判断标准无法并行 ：只能串行处理，5000 个商品要等很久结果难以解析 ：AI 输出格式不一致，后续脚本难以处理把审核逻辑封装成一个 Skill，让主 Agent 调用。
改进点：
Skill 可以复用，审核逻辑标准化 可以分批处理，降低单次上下文压力 依然存在的问题：
上下文累积 ：每批的输入输出仍然留在主对话中无法真正隔离 ：所有 Skill 调用共享主 Agent 的上下文并发受限 ：Skill 仍是串行执行，无法并行加速为审核任务创建独立的 Subagent，每个 Subagent 处理一批商品。
核心优势：
上下文隔离 ：每个 Subagent 拥有独立的上下文，互不干扰可并行处理 ：多批审核可以同时进行（理论上）输出标准化 ：Subagent 严格按照定义的 JSON 格式输出主 Agent 轻量 ：主 Agent 只做调度，不接触数据内容简单来说，Subagent 就是一个可以被主 Agent 调用的 "专家助手" 。
你可以把它理解为：
函数 ：定义好输入输出，主 Agent 调用时传参独立进程 ：拥有自己的上下文，不污染主 Agent专业顾问 ：每个 Subagent 可以有自己的专业领域和工具集不过，不要太纠结概念 。接下来通过实战，你会直观理解 Subagent 是怎么工作的。
最初我想直接让 Claude Code 处理，但很快发现问题：
上下文爆炸 ：5000 个商品 + 分类表 + 审核结果，轻松超出上下文限制串行处理慢 ：逐个商品判断，效率太低结果混乱 ：长对话中，Claude 容易 "忘记" 之前的判断标准Subagent 天然解决这些问题：
痛点 Subagent 方案 上下文爆炸 每个 Subagent 独立上下文，互不干扰 处理效率 批次并行处理 结果一致性 每批独立审核，标准统一
在 .claude/agents/ 目录下创建 category-reviewer.md：
---
name: category-reviewer
description: 商品分类覆盖审核专家。当需要批量检查商品是否被现有分类表覆盖时使用。
tools: Read, Write
model: sonnet
你是商品分类覆盖审核专家。
## 输入说明
调用时会提供：
- batch_id: 批次编号 file: 商品列表文件路径
- output_file: 结果输出文件路径 file，获取商品列表
2. 使用 Read 读取 `doc/goodscategoryreview/标准化分类体系表.md` 3. 逐一判断每个商品的分类覆盖情况
4. 将结果 JSON 写入 output_file**covered** ：商品名称能够明确归入现有某个分类**uncovered** ：商品无法归入任何现有分类 file 的 JSON：
{
"batch_id": "xxx", category": "匹配的分类"},
{"name": "商品B", "status": "uncovered", "reason": "原因", "suggested_category": "建议分类"} ## 注意事项 - 每个商品都必须有一条记录，不要遗漏
- status 只能是 "covered" 或 "uncovered"
- 相似商品的 suggested_category 保持一致 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：
我需要找出商品清单中所有未被现有分类覆盖的商品。
## 文件路径
- 商品清单：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
│ ├── batch_002.txt
│ └── ...
├── batch_001.json
├── batch_002.json
├── ...
├── batch_count.txt
├── summary.json
└── report.md 本文的实战方案中，只有审核环节用了 Subagent，其他步骤（数据准备、汇总统计、报告生成）还是通过 Python 脚本完成的。
其实，我们可以把整个流程的每个环节 都交给专门的 Subagent 处理，这样就形成了一个多人协作的 AI 团队：
AI 团队协作架构 项目经理 负责任务调度和协调 data-preparer category-reviewer result-merger report-generator 读取商品清单并分组 批量审核商品分类 合并审核结果并统计 生成审核报告 错误 ：让 Subagent 输出 “已覆盖数量: 25, 未覆盖数量: 5”
问题 ：AI 不擅长精确计数，容易出错
正确 ：让 Subagent 逐条输出每个商品的判断结果，用脚本统计数量
错误 ：每批完成后，主 Agent 读取 JSON 文件检查结果
问题 ：167 个批次的 JSON 内容全部进入上下文，直接爆炸
正确 ：主 Agent 只确认完成，最后用脚本统一汇总
错误 ：
使用 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
大量同质化任务（如本文的批量审核） 需要隔离上下文的独立子任务 可并行处理的工作 需要专业化 prompt 的特定领域任务 不适合用 Subagent
简单的一次性任务 需要持续对话、多轮迭代的任务 强依赖上下文连贯性的任务 Subagent 是 Claude Code 中非常强大的功能，但用好它需要注意上下文管理 。核心思路就是：
主 Agent 是调度员，不是搬运工。数据流转靠文件，不靠对话。
希望这篇实战分享对你有帮助。如果你也有类似的大规模数据处理场景，不妨试试 Subagent + 脚本的组合方案。
本文基于 Claude Code 实际使用经验撰写，欢迎交流讨论。
📌 转载信息
转载时间： 2026/1/10 18:59:58
