mainagent-context-budget

name	mainagent-context-budget
description	教 mainagent 何时 / 如何把任务分发给 subagent 来控制主线程上下文预算，并判断哪些独立任务适合并行、如何回收和验证结果。当任务命中「读超过 5 个文件 / 包含搜索 / 输出超过 500 行 / 主线程已 30+ tool call / 用户说调研/分析/扫一遍/梳理」任一条时启动。触发词：分发任务、上下文预算、主线程上下文、要不要 dispatch、subagent 分发、长任务、调研、扫一遍、避免上下文爆炸、context budget、控制上下文、mainagent context、上下文要爆了。

mainagent-context-budget

主线程是协调者，不是执行者。这个 skill 教 mainagent 何时把任务分发给 subagent，以及怎么把任务分发清楚。

为什么需要

主线程上下文是有限资源。一旦被原始数据淹没——读 50 个文件、跑 30 次 grep、看 1000 行报告——主线程会：

• 丧失"协调 + 决策 + 聚合"能力
• 后面每条用户消息都要重新读已被污染的历史
• 触发 compact，丢失关键早期决策

正确分工：

• 主线程：理解需求、决定路径、对齐用户、聚合结论、做最终判断
• subagent：脏活累活（搜索、读文件、生成长报告、并行任务）

何时必须分发

下面任一条命中就 dispatch：

信号	判断标准	处理
多文件读取	需要读 >5 个文件	dispatch
包含搜索	grep / find / glob 等	dispatch
长输出	预计 >500 行 / >5k token	dispatch + 要求 subagent 摘要返回
主线程已重	已做 30+ tool call	后续非聚合任务都 dispatch
用户用了关键词	"调研"、"分析"、"扫一遍"、"全面看一下"、"梳理"、"统计"	dispatch
重复执行	同样的操作要做 N 次（如改 N 个仓库）	并行 dispatch N 个

何时主线程自己做

场景	为什么不 dispatch
单文件 read + 单文件 edit	dispatch 成本 > 收益
1-2 个简单 bash 命令	同上
需要跟用户对齐的判断	subagent 不能问用户
最终聚合 / 总结	这就是主线程的职责
反思 / 回顾当前对话	subagent 看不到对话
写最终给用户的回复	主线程负责输出

写好 subagent prompt 的纪律

必含 6 字段

subagent 没有当前对话上下文。每个 prompt 都要自包含。

1. 背景（1-3 句）：项目是什么、要解决什么问题
2. 任务（1 句）：它具体要做什么
3. 输入：具体文件路径 / 数据源 / 已知参数
4. 输出格式：明确要求 markdown 表格 / JSON / 多少字以内
5. 执行预算：最多读 N 文件 / 最多 M tool call / 多少字以内
6. 要回报什么：摘要结论 + 关键数据 + 不确定的部分

会修改文件的任务还要明确：允许改哪些路径、禁止碰哪些路径、能否与其他 agent 共享资源，以及「禁止执行 git add / commit / push / reset」。排障任务应附上准确错误、复现方式和已知证据，别只写「修一下」。

不要做的事

• 不要要求 subagent "理解" 或 "判断" —— 它没有用户场景的背景
• 不要让 subagent 输出原始大量数据 —— 让它摘要 + 引用证据
• 不要 dispatch "做完所有 X" 这种无边界任务 —— 给清晰边界
• 不要让 subagent 跟用户对话 —— 没有这个通道
• 不要把"决策"分发出去 —— 决策是主线程的核心职责
• 不要让"会改文件"的 subagent 自己跑 git（add/commit/push/reset）—— 多个 agent 各自提交会让主线程 git 状态分叉、甚至把已删的 commit 推回 origin。改文件归 subagent，提交/推送归主线程；prompt 里写死一句「只改文件本身，不要执行任何 git 操作」

并行前先检查独立性

只有同时满足下面条件，才并行 dispatch：

• 每个子任务能在边界清晰的上下文里独立完成。
• 子任务没有先后依赖，一个结果不会改变另一个任务的输入。
• 不会修改同一文件、共享可变状态或争用同一外部资源。
• 每个结果能单独验证，主线程也能明确地集成它们。

如果多个失败可能来自同一个根因，先按问题域合并调查，别机械地按文件一人一个。探索性排障尚未划清边界时，也先由一个 agent 建立全局事实，再决定是否拆分。

并行调度

• 按独立问题域分组，而不是按文件数量分组。
• 在同一轮里发出所有可并行的 dispatch；分多轮逐个发送会退化成串行。
• 遵守当前运行时并发上限，并记住主 agent 自身也占一个槽位；任务更多时分波次执行。
• 会编辑文件的 agent 必须拥有互不重叠的路径；无法隔离就改为串行。
• 不要为了“用满并发”拆出过小任务，dispatch 成本应低于节省的时间和上下文。

并行示例：

• 改 5 个互不依赖的仓库 → 每仓一个 agent，在并发上限内分波次。
• 调研 4 个独立信号源 → 4 个 agent 同时收集，主线程综合。
• 对比 6 个 SKILL.md 风格 → 1 个 agent，因为结论依赖横向比较。

摘要返回的强制约定

subagent 必须按下面格式回报，主线程才能高效消费：

## 关键发现
- 3-5 条 bullet，每条不超过 1 行
## 量化数据
- markdown 表格或关键计数
## 不确定的点
- 等主线程决定的 1-3 条
## 引用证据
- 文件路径 + 行号 / URL，最多 5 条

严禁让 subagent 把全部读到的内容堆给主线程。如果产物是大文件（>200 行），让 subagent 写到磁盘，回报路径就行。

回收与集成验证

agent 返回后，主线程不能直接转述“已完成”：

验证强度要与风险匹配：只读任务抽查关键证据，局部修改检查 diff 并跑针对性验证；只有多个结果共享接口、状态或组合行为时，才追加组合验证。不要默认运行与改动无关的全量测试。

1. 读摘要，确认回答了原任务且没有越界。
2. 对修改任务检查真实文件、git diff 和工作区状态；对只读任务抽查关键证据。
3. 检查多个结果是否碰了相同文件、依赖矛盾或得出冲突结论。
4. 先跑各子任务的针对性验证，再跑必要的组合验证，避免“各自通过、集成失败”。
5. 只报告实际验证过的状态；失败或无法验证时明确说明剩余问题。

触发场景速查

用户说	是否 dispatch	为什么
"查下 README 在哪"	❌	主线程一个 glob 就够
"读一下这个文件"	❌	单文件
"把所有 service 类找出来"	✅	搜索
"分析最近三个月的代码变化"	✅	大量数据
"看一下这个 PR 怎么改的"	❌	单 PR
"对比这 5 个 PR 的风格"	✅	多文件 + 分析
"扫一下仓库找 TODO"	✅	全仓库搜索
"把对话总结一下"	❌	subagent 看不到对话
"给我每个仓库 build 一遍"	✅ 并行	独立 + 重复
"梳理一下这块代码的依赖关系"	✅	用户说"梳理"+ 多文件

上下文已偏重时的应急

如果你（主线程）出现以下信号，要更激进地分发，所有剩余非聚合任务都 dispatch：

• 已经做了 30+ tool call
• 已经读了 10+ 个文件
• 单次 token 摄入 > 20k
• 用户开始抱怨"太慢"或"卡住"
• 你自己感觉"我刚才在干嘛"——说明上下文已经被噪声淹没

这时不要再贪心"我顺手做完吧"，立即 dispatch。

与已有相关 skill 的关系

• superpowers:subagent-driven-development —— 关注执行实现计划时怎么用 subagent。本 skill 关注任何任务的上下文预算。
• systematic-debugging —— 多个失败是否独立尚不清楚时，先建立根因证据，再决定按问题域并行。
• verification-before-completion —— agent 自报完成不算证据；主线程集成后仍需 fresh verification。
• handoff —— 当上下文已经爆了想"换一份干净的主线程"，走 handoff；本 skill 是预防handoff 被触发。

反例（不要这么干）

• 反例 1：用户问"梳理一下最近 30 天的工作历史"，主线程自己 ls + grep + read 几十个文件 → 应该 dispatch
• 反例 2：dispatch 一个 agent 让它"看下这个文件然后回复用户的问题" → 主线程要负责回复用户，subagent 只负责读
• 反例 3：dispatch agent 让它输出 2000 行报告 → 应该让它写到磁盘 / 摘要返回
• 反例 4：把 4 个独立任务串行 dispatch（4 条 message） → 应该一条 message 里同时发 4 个
• 反例 5：subagent 报"我提交了 5 个 commit"，主线程直接信 → 应该跑 git status 实测（这有专门的 subagent-verify hook 做这件事）
• 反例 6：并行 dispatch 多个改文件的 agent，没在 prompt 里禁止 git → 某 agent 擅自 git commit 两个仓库、还把已 force-push 删掉的 commit 推回 origin，主线程花了很多轮 git -C 排查 + reset --mixed 合并才收敛。改文件的 agent 一律加「禁止 git 操作」约束，提交由主线程统一做