AI-Wiki

定义

文件化任务交接，是指在 Superpowers 6.0 的 SDD（subagent-driven development）流程中，把任务执行与评审所需的交接材料，从“堆在主对话里临时传递”改成“写成工作树中的文件并持续复用”。

它不是单纯把内容落盘备份，而是把 brief、diff 包、进度账本都变成流程中的正式交接物。

这套做法的目标很明确：

implementer 不必在主会话里反复接收整段计划全文；
reviewer 不必自己运行一串 git 命令临时还原改动；
controller 不必不断把 diff、任务边界和进度复制进对话；
长任务在中断后可以依据文件恢复，而不是依赖模型“记得之前聊过什么”。

因此，文件化任务交接可以看作 AI 工程纪律在长任务执行阶段的一种具体落地形式。

在本文档中的语境

在本文语境里，这个概念出现在 Superpowers 6.0 对任务实现与评审链路的重写中。旧做法的问题不是没有评审，而是交接成本太高：

同一段任务上下文会被 implementer、多个 reviewer、controller 重复消费；
主会话容易被每个 task 的 diff 反复挤占；
reviewer 容易从“检查当前任务”滑向“顺手看整个仓库”；
长任务一旦中断，恢复时常常需要重新拼接上下文。

6.0 的思路是把这些高频交接材料文件化，并围绕它们组织单任务实现、单任务评审和进度恢复。这样做并没有降低质量门槛，而是通过明确输入物和边界，减少上下文浪费与流程漂移。

核心组成

1. task brief：面向 implementer 的单任务说明

task brief 由 scripts/task-brief 生成。它会从整体计划中抽出单个任务，写成：

.superpowers/sdd/task-N-brief.md

这里的关键点不是“多了一个文件”，而是任务派发方式变了：implementer 不再需要在主会话中接收整段计划全文，而是直接读取当前任务对应的 brief。

这意味着：

任务输入被压缩到当前 task 所需的边界；
实现者关注的是“这一小步要做什么”，而不是重新消化整个长计划；
controller 不需要在每次派发时重复粘贴完整计划；
如果计划本身拆得足够细，brief 就能把实现范围限制在当前任务内。

它与 AI编程任务细粒度计划拆解、任务颗粒化计划是直接配套的：计划先被拆成 2 到 5 分钟级别、验收明确的小任务，再由 task brief 把其中单个任务提取出来交给 implementer。

2. review package：面向 reviewer 的差异包

review package 由 scripts/review-package 生成。它基于 base 与 head 生成一个 diff 包，供 reviewer 直接阅读。

其核心内容包括：

commit list
files changed
带上下文的 net diff

这三个部分组合起来，分别回答三类问题：

commit list：这个任务期间发生了哪些提交；
files changed：影响面落到了哪些文件；
带上下文的 net diff：最终净变更具体改了什么、在何处改、上下文是什么。

6.0 的设计要求 reviewer 直接读 review package，而不是：

自己手动执行一串 git 命令去拼 diff；
依赖 controller 在对话中粘贴大段 patch；
先在会话里听一轮“发生了什么”的口头转述。

这样做的意义在于把评审输入标准化。reviewer 拿到的是同一种结构化材料，而不是每次都靠临场还原。对于失败后的修复环也一样：可以继续围绕同一个 brief 和同一个 diff package 迭代，不会在 prompt 里越补越乱。

3. progress ledger：面向恢复与续跑的进度账本

progress ledger 位于：

.superpowers/sdd/progress.md

它的角色是长任务恢复时的账本，用于定位哪些任务已经完成、哪些还没有完成。

在新版流程中，只有当单任务评审通过后，任务才会被写入这个 ledger。这样一来，账本记录的不是“做过尝试”，而是“已经通过当前门槛的进度”。

它最直接的用途是恢复：当上下文压缩、会话中断或分支暂停后，controller 可以结合 progress ledger 与提交历史，找到第一个未完成任务继续执行，而不是从头回忆整条链路。

这使得多小时、甚至多天的 Agent 开发更可恢复，也更接近工程上的可审计流程。

协作机制

implementer 如何交接

在 文件化任务交接 中，implementer 的输入核心不再是“主会话里的一大段计划说明”，而是当前任务对应的 brief 文件。

这带来两个边界变化：

implementer 的关注范围被收窄到当前 task；
主会话不再承担完整任务上下文的长期缓存功能。

换句话说，主会话从“承载全部任务细节的容器”，变成“调度与控制入口”；而任务细节本身则沉淀到 .superpowers/sdd/ 下的文件。

reviewer 如何交接

reviewer 的输入核心不再是 controller 粘贴出来的一段对话材料，也不是自己现场跑 git 命令构建上下文，而是 review package。

这与 6.0 的评审边界设计是配套的：reviewer 被要求优先阅读任务 diff，并给出双重结论，而不是把评审扩展成一次无边界的全仓库巡检。

因此，review package 不只是“为了方便”，它还是 reviewer 收敛注意力的主要载体。标准化的 diff 包会把评审活动压回当前任务，减少低价值搜索。

controller 如何交接

controller 不再承担“对话搬运工”的主要角色。它的工作更像流水线调度：

从计划生成 task brief；
在实现完成后生成 review package；
在评审通过后更新 progress ledger；
在中断恢复时读取 progress ledger，定位下一步。

也因此，controller 对主会话 token 的消耗下降了。交接材料尽量停留在文件中，而不是在主对话里反复展开。

关键收益

降低主会话上下文成本

这是这套机制最直接的收益。长任务中，主会话不再被每个 task 的计划片段、实现报告和大段 diff 反复挤占。

过去常见的问题是：每完成一个任务，就要把当前任务边界、改动说明、diff 摘要、评审输入重新塞回主会话；任务一多，上下文就会被重复内容吞掉。文件化后，这些信息转移到了工作树中的持久文件。

减少重复阅读与重复转述

implementer 读 brief，reviewer 读 review package，controller 读 progress ledger。每种角色有更明确的输入物，不必都围绕同一大段对话重复消费上下文。

这与任务级双结论代码评审的变化相互加强：6.0 已经把旧版“两个 reviewer 分别看同一 diff”改成“一个 reviewer 一次阅读，给出两个 verdict”；而文件化交接进一步减少了 diff 在会话中的重复传播。

让长任务可恢复

一旦任务跨越多个小时或多天，仅依赖会话历史恢复是很脆弱的。通过 .superpowers/sdd/progress.md 记录通过门槛的任务进度，再配合任务 brief 与 review package，恢复时就能更快定位当前状态。

这使恢复动作从“重新讲一遍前情提要”变成“读取账本并继续执行”。

让失败修复环更稳定

如果评审失败，修复环可以围绕同一个 brief 和同一个 review package 继续运转。