| 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-3 句）：项目是什么、要解决什么问题
- 任务（1 句）：它具体要做什么
- 输入：具体文件路径 / 数据源 / 已知参数
- 输出格式：明确要求 markdown 表格 / JSON / 多少字以内
- 执行预算：最多读 N 文件 / 最多 M tool call / 多少字以内
- 要回报什么：摘要结论 + 关键数据 + 不确定的部分
会修改文件的任务还要明确：允许改哪些路径、禁止碰哪些路径、能否与其他 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 并跑针对性验证；只有多个结果共享接口、状态或组合行为时，才追加组合验证。不要默认运行与改动无关的全量测试。
- 读摘要，确认回答了原任务且没有越界。
- 对修改任务检查真实文件、
git diff 和工作区状态；对只读任务抽查关键证据。
- 检查多个结果是否碰了相同文件、依赖矛盾或得出冲突结论。
- 先跑各子任务的针对性验证，再跑必要的组合验证，避免“各自通过、集成失败”。
- 只报告实际验证过的状态；失败或无法验证时明确说明剩余问题。
触发场景速查
| 用户说 | 是否 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 操作」约束，提交由主线程统一做
