Running subagent teams

子代理团队运营（派发 / 档位 / 成本 / 审查经济）

When NOT to use

≠ dispatching-parallel-agents（彼=判断哪些任务可并行）、≠ subagent-driven-development / executing-plans（彼=单会话调度/按written-plan执行）；此=子代理团队的长期运营经济学与纪律。

子代理审查右量化

子代理审查右量化：M 级及以下一律合并单审（一个审查代理带"规格符合+ 代码质量"双清单，档位不降）；两段审只留 L 级或动核心语义/跨系统契约的改动 （实测：外围迁移类两段审 token 达实现侧 2.2 倍、两审工作重叠 ~60%）。审查 代理禁止重跑全量——控制者把红绿证据（全量结果+SHA）写进派发词，审查只做 静态核对+至多复跑 1 个单测。评审跟进若是逐字应用评审措辞 → 控制者直改+解析 检查免二次回路（仅限纯惰性改动：改名/注释/格式；动类型/类型转换/控制流/ 生命周期者走正常验证——解析检查逮不到 runtime 错）。审查重量要匹配改动风险。

子代理与会话经济（长项目实测产物）

1. 派发简报文件化：子代理的公共环境/纪律块放进仓库一份 DISPATCH-BRIEF 类文档（单一事实源），派发词=一句"先读简报"+任务专属内容。 禁止逐次重复粘贴——某迁移项目实测 15+ 次派发重复 ~20k token 且产生漂移。 派发前声明拆解判断：用一行写明「1 顺序任务 / N 独立任务 + 各归属谁」， 单代理领大任务附一句"为何不可拆"（顺序依赖/共享状态）——把并行/串行判据 显式化，既堵控制者图省事把独立块捆成一坨、又给监督者一个审查点。事故： 监督者观察到"只开一个子代理却任务很大"时无从判断是本就不可分还是欠拆解。 （注：架构是单层轮辐式，子代理为终端、不再向下派发；若要硬性防止应走机械 载体——删子代理定义的 Agent 工具，而非立散文规则，零发生的问题不预防。）
2. 子项目收口即换新会话：验收通过时把断点写进持久记忆（进度指针+经验 增量+下一步+成本快照——本段各档派发/红轮/升档/tokens 账本+一两句 卡点/摩擦；收口复盘合并各段快照，否则换会话即丢复盘原始数据，只能 复盘最后一段），主动建议开新会话；不要拖到上下文见底被迫断。断点三层 保险：仓库（提交+push）、计划文档（在库）、记忆（会话专属增量）。 断点必带交接头：凡向监督者报断点/建议换会话（收口换会话与长上下文红线均算）， 正文末固定附两件——①衔接关键词：可直接发给下一会话、令其一句话无缝接续的指针 （当前主线+进度+下一步动作+权威设计/记忆路径）；②建议模型×effort：按档位指南 判下一会话性质后给出。理由：断点写进记忆只服务 AI 自己，监督者换会话仍要翻记忆拼 上下文、且开场常把模型/effort 设错（贵或不够）——把接续关键词与该用什么档放进报告 那一刻，直接消除交接摩擦。 收口触发器要多元化、别只挂"任务终点"：两个失败模式合流——(a) 特性横跨 多个被上下文红线切断的断点、始终没遇到干净收口时刻；(b) 任务被中途新增子任务 递归撑开、永不抵终点。两者都让"只在收口才做的工序"（成本复盘、面向人的叙事 记录/devlog、瘦身审计）漏成孤儿——没有任何单会话处在"做完该收口"的位置。修订： ①收口绑交付（验证+push 的增量）而非"整件事做完"，每次交付做一次几分钟的 轻收口；②断点清单逐项查收口工序欠账、在上下文湮灭前转移（写进断点指针）， 不止记进度；③中途加 scope 即显式分叉（点名新任务+原任务状态、可交付增量先 提轻收口、新意进 backlog 而非就地递归；默认提议不硬拦——递归里常含实现中发现的 真需求，可见可选比禁止更治本）。事故：某项目面向人的叙事日记连续两日 35+ 提交 零更新，根因即"收口只挂任务终点、而任务在递归扩张里永不抵终点"；且与早先"成本 复盘数据随换会话湮灭"是同一根因的不同侧面（当时补丁只纳入成本快照、漏了叙事记录）。
3. 计划默认 directive 风格：迁移/平移类工作以"既有文本=行为规格+改动点 清单"写计划，全码只给真正的新逻辑——全码式与 directive 式实测交付质量 等效，后者成本减半（省去控制者预读全部源码）。
4. 子代理落地与报告纪律（子代理回合结束即死，报告是它存在过的唯一证据； 一次事故：实现者以"等待后台验证完成"收尾——通知无处可送，报告丢失+全部 工作悬空未提交，控制者被迫法医重建）：
   • 后台收割纪律：允许后台真并行（如全量测试期间备提交材料），但报告/提交 前必须前台收割一切异步；严禁以"等待"作为最后动作；无可重叠工作就 前台跑（阻塞等待不烧 token，轮询才烧——禁一刀切是经评估的取舍）。
   • 先落地后报告：验证→提交→才写报告（报告丢失时工作已 durable）。
   • 报告须 SendMessage 送达控制者：子代理最终回合的文本输出不会自动送达 控制者——后台派发下控制者只收到它的 idle 通知、看不到报告正文。写完务必 SendMessage({to:"main", ...}) 发出（状态+SHA+红绿+concern）；不发=控制者收不到、 被迫每任务手动 poke 或 git 取证。BLOCKED/提问同理（派发词也应显式要求「完成 SendMessage main」）。
   • commit message 即报告备份：红绿证据/关键数字/偏差入提交正文， git log 可独立还原。
   • 报告硬上限 ~500 字：通过项一行列举——长报告烧控制者上下文，且随 会话推进被逐轮重复计费。
   • 控制者处置序：报告丢失/截断 → 先 SendMessage 原代理要补报（上下文 还活着），不可达才 git 取证。
5. 瘦身审计（开工+收口两侧，助手主动，用户免提示）：开工侧——M/L 级 开期/规格阶段必答落点既有代码要不要先瘦身（语义双拷贝/待替换硬编码/测试 耦合），大瘦身撞新增落点 → 瘦身前置为该特性首任务、瘦身量计入判级（脏 地基上加层=双倍返工）。*规格/调好的数值落产品单一真源（Def/config/导出属性）， 测试硬编规格值则产品必须从同一权威位读——否则绿测不证游戏生效。 收口侧三问——①脚手架拆了吗（临时节点/探针/ 占位物；受控的人工验收场景属维护资产、本问豁免）；②有没有语义重复的成对 常量/算法（单点化，防调参分叉——实例：迁移期新旧两模块各持同值门常量，谁 先调参谁制造分叉）；③"原值平移/兼容"政策带进的死配重能摘除验证了吗（实例： 旧引擎的防弹飞补丁在新物理引擎下疑似无事可做——做摘除实验而非直接信或 直接删）。里程碑收口做全仓版；结论写进复评项清单，不靠任何人记忆。 里程碑收口记忆审计：过一遍持久记忆索引，按记忆type 而非提及频率 决定去留——project 进度快照随项目收口即删或压成一行教训；feedback/user 类近乎永久（低频≠低价值）；reference 类失效（链接死/工具下线）才删。 收口成本复盘（同样助手主动）：每子项目/大阶段收口（尤其全量测试 收尾后）回头主动汇报——①卡点（红绿往返/探针轮数/墙钟最久的环节） ②token 热点（子代理 usage 账本分项 + 主会话上下文水位）③流程摩擦 （哪步纪律产生额外成本、或没拦住本该拦的问题）④附 1-3 条按预期收益 排序的工作流完善方案，用户勾选后才入修订记录。教训：成本复盘若依赖 用户自查用量面板，发现时 token 已经超限。
6. 子代理模型分级（档位抽象，规则不绑型号）：四档——T-省（纯机械/ 照抄/文档）、T-标（配方迁移/多文件集成）、T-强（新逻辑实现/常规 审查）、T-尖（最深语义/根因攻坚/深审）；项目文档里维护一行 "档位→当前模型名"映射，换代只改该行（防基线漂移——模型名硬编码与 shell 版本硬编码是同一类坑）。T-强/T-尖 要分开：上游"次强档"常是 最强档半价且代码审查/调试恰为其强项，而审查往往是子代理最大开销—— 全押最强档等于把最大开销项放在最贵的档（实测教训）；用公开定价核对 后再定映射。升级阶梯：BLOCKED/红两轮/需探针 → 升档重派，禁同模型硬试； 审查不对称：实现可降档、审查不跟降——落地为审查配对：T-尖实现 的产出必须 T-尖深审，其余可 T-强审（弱实现+强审查稳健，反之最差）。 前提：该分级只在"失败响亮"的流程里安全（TDD 先红/全图解析测试/启动 捕获/审查回路）——没有这些网，弱模型会悄悄做坏。换代时新模型先跑 标定样本再上量。最高 effort 档（max 类）官方常提示易过度思考，留作 手动单次升档，不入默认表。切点由数据移动，不靠辩论：收口成本复盘 交"档位校准账本"（每派发目标的使用次数/红轮/升档/tokens），触发器= 连续两个子项目某档零使用、或升档率 ≥1/3 → 提切点修订案。控制者 会话本身也按"审查不得弱于实现"推到顶：驾驶项目用 T-尖档模型 + 标准高 effort 起步，设计拍板/亲自根因/复盘归因时临时升最高深思档， 事毕切回；纯执行会话可降一档省半价（但中途升不了模型——模型中途切 会废提示缓存，开场定死）。档位哨兵（人也会忘切档——用户+主会话同样 是个派发目标）：用 harness 钩子（如 UserPromptSubmit 注入 additionalContext）每轮把当前 effort/model 喂给助手，助手负责失配 报警：升档先停（一行"建议切 xhigh，切完说继续"）、降档即提（滞留 高档是静默漏费）、开场核对；报警克制，类型明确才触发。哨兵本身也会停摆（钩子快照常按进程 固化，改完不重载就静默失效）——首轮未见注入即视为哨兵失效信号： 助手改手动核对档位并提醒检查钩子配置，静默即报警。 effort 同为档位维度，且与主会话全局值完全解耦："继承全局"是双向 隐藏耦合——全局高档悄悄放大所有子代理成本，全局调低又悄悄封顶子代理 的高档（实例：主会话降档后，靠继承实现的最高档调试通道静默失效）。 一律用代理定义文件（.claude/agents/ frontmatter effort 字段）按 "模型×effort"钉死：经济档省略、标准档 medium、强档实现 high、根因攻坚 与核心深审 xhigh，不留继承通道。简单操作配高 effort 属过度工程； 高 effort 只买"想不透就交付不了"的环节。 经济档要真的用：纯挂载/照搬/台账类强制先试经济档，红了再升档（实测 一个子项目跑完经济档零启用 = 白设了一档）；"惊喜密集期上浮一档"偏置 仅适用于新逻辑类任务，机械/照搬类不偏置。
7. 主会话切换点：任务边界优先，标准切换点 + 硬上限兜底：自然任务边界处直接 收口换会话（任务一完就清空/新开跑下个独立功能，不为凑数拖旧会话）；无自然边界 时定一个标准切换点（到点写断点+开新会话）和一个硬上限（必须收口换会话），其间 同任务可继续推进。具体数值随模型上下文容量与计费结构定——若有计费阈值（如某些 长上下文模型 >200k 输入费率翻倍）就把切换点压到阈值附近图省钱；否则按"旧对话/ 废弃方案/工具输出累积到开始干扰判断"为准，容量大也别一直用满。 弃用 /compact 续同会话当交接手段：有损且不可审计，精确事实（SHA/路径/未决 决策）易被悄悄丢；写断点+开新会话的交接更可靠、可审、零旧决策污染。
8. 无人值守长跑：预审队列（睡前批量确认决策，把人的决策前移）+ 台账 WAL （状态外置、中断可续）+ 心跳自愈；夜间禁对外操作（push 等）、降到标准档 自主度，晨间收工复核。根因：无人值守的本质是决策者与执行者不同时在线， 靠决策前移+状态外置补；安全网（TDD/全量/审查）照走、人工验收显式留到晨间。