用途
Post-Review Loop 是一个面向代码变更的“实现后审查循环”工作流。它在代码实现已经存在之后进行事后审查,重点发现那些通过真实接口、状态、控制流、测试、文档或模块边界才变得可见的问题。该技能以显式 Codex 工作流的形式模拟 Pi 的 post-review-loop;由于 Codex 无法持有隐藏的扩展状态或注入后续提示,因此将循环状态保存在对话中(用于一次性工作)或可见的账本中(用于多轮或恢复的循环)。
主要能力
模式
从自然语言中解释用户请求的模式:
- oneshot 或无模式:审查实现一次,可选地应用安全修复,验证并报告。
- review-only:审查一次,不编辑文件。
- start:创建持久循环账本并运行第一阶段。
- continue 或 resume:读取账本并运行下一阶段。
- status:报告当前生命周期、阶段、未解决的分桶、验证和下一步动作,不更改文件。
- report 或 stop:渲染最终或当前报告。如果已经在工作,则在当前阶段后停止。
- cancel:立即停止,如果存在账本则留下简短的取消说明。
默认审查范围是未提交的变更。如果用户指定了分支、提交范围、功能、文件列表或实现目标,则使用该范围。
账本
仅对 start、continue、resume、status、report 或无法在一轮内完成的工作使用显式账本。优先使用目标仓库根目录下的 reviews/post-review-loop.md,除非仓库已有更好的审查状态约定。
账本结构包含:生命周期(active | paused | finalizing | complete | cancelled)、范围、阶段(post-review | impl-review | impl | final-report)、迭代次数/上限、是否 review-only、基线;以及“审查了什么”“Bucket I - 安全范围内修复”“Bucket II - 需要决策”“已应用的代码变更”“验证”“阶段日志”等表格与章节。账本被视为权威来源:如果不在账本中,就没有发生。保持简洁,不要变成对话记录。
审查视角
在实现存在之后进行审查。在决定之前检查真实文件和差异:
- 对于未提交的变更,检查 git status --short、git diff、git diff --staged 以及相关的未跟踪文件。
- 对于分支、提交范围或指定范围,检查该目标及附近的接口、测试和文档。
- 区分由变更引入的问题与仅仅被变更暴露出来的既有债务。
- 干净的审查是有效的。不要编造发现。
将有意义的问题归类为恰好一个设计信号:简单的局部错误;验证或不变式缺口;所有权/边界不清;类型或模式模型薄弱;状态、生命周期、并发或顺序风险;过度抽象、抽象不足或重复逻辑;脆弱的集成或契约不匹配。
优先根因发现而非表面修饰。拒绝推测性偏好、宽泛的未来防护、微小辅助函数提取、命名修饰、孤立去重或日志美化,除非它们揭示了更广泛的边界、不变式、所有权、模式、生命周期、抽象或集成问题。
分桶
- Bucket I 是自动修复轨道。仅当问题具体、安全、在范围内、有实质用处且现在可根因修复时使用。除非用户要求 review-only,否则自动应用 Bucket I 修复。
- Bucket II 是决策轨道。当真正的改进需要产品、领域、架构、发布、兼容性、变更量或风险判断时使用。未经用户明确批准,不要实现 Bucket II。
- Keep As-Is 用于在检查后拒绝的有意义关切,因为证据薄弱、当前结构值得保留,或变更会是过度纠正。
当安全的 Bucket I 修复暴露出可能的更广泛重新设计时,在适当情况下应用安全修复,并将更广泛的选项记录为 Bucket II,包含选项、权衡、建议以及为什么需要批准。当聚焦修复明显足够时,不要制造更广泛的选项。
阶段循环
持久循环使用以下阶段顺序:
post-review -> impl-review -> impl -> post-review -> ... -> final-report
阶段规则:
- post-review:审查当前差异和附近架构。不编辑代码。记录 Bucket I 候选和 Bucket II 决策。
- impl-review:针对真实代码路径和测试重新验证每个可操作的 Bucket I 项。不编辑代码。将安全项标记为已接受;拒绝、降级或将不确定项移至 Bucket II。
- impl:紧密实现已接受的 Bucket I 修复。将已修复项标记为已应用,记录代码变更并验证。
每个阶段后的门控:
- 在 review-only 中,审查报告后停止。
- 如果范围/上下文不足,停止并说明需要范围或上下文。
- 如果验证阻碍安全继续,停止并说明验证失败仍然存在。
- post-review 后,仅当存在 Bucket I 候选且未达到迭代上限时继续。如果只剩 Bucket II,停止等待决策。
- impl-review 后,仅当存在已接受的 Bucket I 工作且未达到迭代上限时继续。
- impl 后,仅当至少应用了一个 Bucket I 修复时才继续到另一个 post-review。
- 当没有已接受/可操作的 Bucket I 发现剩余时,干净地停止。
持久循环默认迭代上限为 5,除非用户给出其他限制。
Git 与验证
不要推送。除非用户明确要求此技能管理带提交的持久循环,或单独要求提交,否则不要创建提交。
当请求提交时:
- 在循环开始时记录起始 HEAD。如果审查脏工作,仅暂存并提交与审查目标相关的变更;必要时使用部分块;保持无关工作不动。
- 使用普通的项目提交信息。不要提及检查点、循环、自动化或内部 ID。
- 在结束时,仅提交循环应用的编辑。如果相关编辑已经提交或没有循环编辑,不要创建重复提交。
在编辑后从仓库现有工作流运行聚焦验证。如果没有运行验证,说明原因。如果验证失败,修复由循环引起的失败,或清楚报告无关/既有失败。
输出
对于 oneshot、review-only 和最终报告,输出以下章节:
-
What I Reviewed:1-3 句简短说明。在有用时区分审查的文件与编辑的文件。
-
Applied / Resolved:列出已应用的 Bucket I 项,包含设计信号、根因、修复、文件和验证。如果没有应用自动更改,写“No automatic changes were applied.”。对于 review-only,将具体 Bucket I 发现列为 [recommended but not applied] 并说明 review-only 模式是未编辑的原因。
-
Needs Decision / Bucket II:列出决策、选项、建议、权衡以及为什么需要许可。如果没有未解决的 Bucket II 决策,写“No unresolved Bucket II decisions remain.”。
-
Keep As-Is:有意义但被拒绝的发现及原因,或省略微小的非发现。
-
Validation:命令和结果,或跳过原因。
-
Verdict:以下之一:No meaningful improvement identified;Applied straightforward design improvements;Applied improvements; decision needed for remaining tradeoff;Decision needed before refactor;Validation failure remains。
对于 status,保持响应更短:生命周期、阶段、迭代、Bucket I 已应用/可操作计数、Bucket II 未解决计数、最新验证结果和下一步动作。
使用方式
通过自然语言指定模式(oneshot、review-only、start、continue/resume、status、report/stop、cancel)来调用。默认审查未提交的变更,也可指定分支、提交范围、功能、文件列表或实现目标。持久循环会在目标仓库根目录创建 reviews/post-review-loop.md 账本(除非仓库已有更好的约定),并按照 post-review -> impl-review -> impl -> post-review 的顺序推进,默认迭代上限为 5。
适用场景
- 代码实现完成后的事后审查。
- 需要多轮、可恢复的审查循环。
- 需要区分可自动修复的安全问题与需要人工决策的架构/产品问题。
- 需要显式记录审查状态、验证结果和阶段进展的场景。
限制
- 不推送代码。
- 除非用户明确要求,否则不创建提交。
- 未经用户明确批准,不实现 Bucket II 项。
- 干净的审查是有效的,不应编造发现。
- 默认迭代上限为 5,除非用户另行指定。
- 关于收费、价格、平台支持等具体信息暂未提供。