dev-plan-review

name	dev-plan-review
description	在评审技术设计文档、实现计划、迁移方案、架构规格、发布与上线计划、插件或 hook 设计、以及需要工程师或代理按文档可靠执行的安全敏感自动化方案时使用；也适用于用户说评审技术方案、审设计文档、看实现计划、方案可不可行等场景。

开发计划与方案评审

概述

多维度技术方案评审，带明确质量门槛。凡会驱动工程落地（改代码、改数据、改配置、自动化、发布）的文档，在进入实现或上线前应经本技能评审。评审围绕七个维度：一致性、正确性、完整性、可执行性、安全性、可验证性、可运维性。

通过标准： 文档能说清要解决什么、由谁执行、如何执行、失败如何收场、用什么证据证明方案成立。方案不必完美，但必须把关键风险显性化并给出可执行的控制措施。不要因文风与个人偏好不一致而否决；也不要放行依赖猜测、口头承诺或不可验收措辞的方案。

交付物： 每次评审须同时给出（1）对话中的结论性说明（摘要、强调阻塞点、必要时口头澄清）；（2）一份可归档的评审文档：按 references/review-output-template.md 填写完整 Markdown，并尽量写入仓库（若用户同意写盘）。清单自检使用 references/review-checklist-template.md，可附在报告附录或单独保存。对高影响或大范围文档，优先采用多子代理分角色评审，由主编排者合并为一份报告，见下文「多子代理评审与交叉验证」。

默认归档路径（可覆盖）： docs/reviews/YYYY-MM-DD-<主题简写>-dev-plan-review.md。子代理分片产出可写入 docs/reviews/...-subagent-<角色简写>.md 或附录，再由主编排者合并为终稿。用户指定其他路径时从其指定。禁止写盘时：在回复中用 Markdown 代码块附上与模板等价的完整文档内容。

何时使用

• 用户提交或点名待评审的设计、实现计划、规格、迁移方案或 runbook。
• 文档将指导工程师或代理直接改代码、改数据、改配置、注册 hook/插件、自动化写盘或触发生产变更。
• 用户询问：评审技术方案、审设计、看实现计划、有没有坑、能否上线、方案可不可行。

不适用： 纯营销文案、与工程执行无关的随笔；换用对应技能。

七维评审

每次评审须覆盖下列七个维度；与文档无关的维度在「评审覆盖」中写一句「不适用」及理由。

1. 一致性

文档内部、与上游规格、与现有系统/代码库之间是否一致？

• 目标、非目标、术语、路径、接口名、版本号、任务顺序、验收标准是否自相矛盾？
• 正文、图示、附录、命令示例是否指向同一套决策？
• 发现矛盾时，是否优先按阻塞实现处理，而不是仅当润色问题？

2. 正确性

方案的因果链是否成立，能否推出承诺的结果？

• 架构、数据流、状态迁移、权限模型、迁移顺序、错误处理是否逻辑闭环？
• 是否说明了「为什么能工作」以及「在什么条件下不工作」？
• 是否存在未论证的关键假设（依赖未就绪 API、未定义语义、未约束并发）？

3. 完整性

完成本次工程变更所需的关键面是否都写到？

• 是否同时覆盖主路径、失败路径、边界条件、依赖、回滚、清理、发布窗口？
• 是否遗漏数据、权限、密钥、监控、人工步骤或合规相关面？
• 「写得长」不等于完整；缺关键决策空白即不完整。

4. 可执行性

执行者能否不靠脑补按文档开工并验收？

• 步骤是否有顺序、输入、输出、责任人与验收标准？
• 任务粒度是否可独立实现与验证？隐藏依赖是否写明？
• 「到时候再看」「视情况而定」是否已改为开放问题或明确约束？

5. 安全性

数据、权限、外部输入与自动化执行的风险是否受控？

• 可信与不可信输入是否区分？写路径与权限是否最小化？
• 涉及 agent、hook、CI、插件、写盘、生产数据时，是否有硬门控或可核验等价物？
• 是否拒绝「人会遵守说明」作为唯一安全措施？

6. 可验证性

用什么证据证明方案成立？

• 自动化测试、手工验收、监控指标、回滚演练、红队样例、数据校验是否对齐风险？
• 测试是否验证行为与不变量，而非仅「命令返回 0」或「能装上」？
• 无法自动化覆盖的部分，手工步骤是否可重复、可判定？

7. 可运维性

上线后能否安全安装、升级、禁用、卸载、回滚与排障？

• 半配置、失败、中断后是否有恢复路径？责任如何交接？
• 可观测性（日志、指标、状态文件）是否足以定位生产问题？
• 高风险、难回滚的变更是否要求分阶段、兼容窗口与门禁？

发现项严重级别

每条发现项须带下列级别之一，格式：[严重|高|中|低]。

级别	含义
严重	不安全、可能丢数据、突破安全边界，或文档矛盾到无法按文档执行
高	常见条件下易失败，或直接阻塞实现、测试或发布
中	模糊、欠测、脆弱或运维薄弱，短期未必阻塞但应修
低	表达、一致性润色、可读性，不单独阻塞结论

文档规模与拆分

大文档难以评审且易藏假设。参考下列规模自检：

~10 页当量或单一子系统     → 适合单次评审闭环
~30 页当量或多子系统耦合   → 应拆成多篇或分阶段评审
「一篇写完全部」且无目录锚点 → 先要求拆分或加摘要与导航

何时允许大块头： 纯索引文档、已机器生成的附录、或与评审无关的参考粘贴（须在「评审覆盖」中排除）。

拆分策略： 按子系统垂直切分；按阶段（设计 → 实现计划 → 迁移/runbook）水平切分；共享契约单独成文，避免同一篇混写「愿景」与「逐步命令」。

评审流程

按顺序执行。途中发现 严重 或 高 级问题，仍完成后续步骤，但在「总体结论」中写明阻塞关系。

Step 1：理解上下文

在逐段抠字前建立坐标：

- 这份文档要推动什么工程变化？
- 谁来执行：人类工程师、agent、CI、运维，还是混合？
- 影响哪些资产：代码、生产数据、用户面、权限、成本、SLA？
- 依赖哪些既有规格、代码、平台能力或流程？

Step 2：抽取方案契约

把文档承诺写成可对照清单；缺项即发现项或开放问题：

- 目标 / 非目标 / 范围
- 组件职责 / 数据归属 / 外部依赖
- 输入、输出、状态变化、持久化格式
- 成功标准 / 失败标准 / 回滚标准
- 兼容性、发布窗口、责任人

Step 3：按七维过一遍

打开 references/review-checklist-template.md 对照「七维」小节，逐维自问并勾选；发现项记入后续报告。

Step 4：追踪主路径与失败路径

不要只扫任务列表。用下列链条走两遍（成功一次、失败一次）：

触发条件 → 执行者 → 输入 → 状态写入 → 外部副作用 → 验证信号 → 清理与终态

对每个外部依赖追问：失败行为、幂等性、部分写、如何检测、如何恢复。

Step 5：标注并分级发现项

确保每条发现项含四件事：级别、路径或章节、触发条件与风险、最小可行修复建议。禁止只有形容词没有动作。

Step 6：验证「验证」本身

- 证据是否覆盖失败、边界、并发、恶意或损坏输入？
- 发布前、发布中、发布后观测是否定义？
- 回滚是否可被验证或演练？
- 手工验收是否可重复、可判定？

Step 7：形成总体结论并落盘

结论须与最高严重级别一致：存在严重问题时不得结论「可直接实现」。 存在 高 问题时默认不得「可直接实现」，除非文档证明该风险已隔离到明确的非阻塞后续阶段。

将完整内容写入按 references/review-output-template.md 生成的评审文档；对话中给出摘要并指向文件路径（或附上等价全文）。若本轮已拆子代理并行评审，由主编排者执行合并与去重，只对外交付一份填好的终稿模板；子代理中间稿可归档为附录或单独文件。

多子代理评审与交叉验证

不同执行者关注不同轴，可补全单视角盲区，并通过重叠维度做交叉验证。

为何需要

• 单代理在长文档上易漏掉失败路径、证据缺口或自动化安全面。
• 分角色迫使用不同「检查透镜」，重叠部分若独立得出同一问题，置信度升高；若结论冲突，须显式进入开放问题或抬高级别。

何时启用

至少满足一条即建议启用 ≥2 个子代理；满足多条或涉及生产、数据、权限、hook、agent 写盘时建议 3 个子代理：

• 被评文档超过约 10 页当量，或多子系统强耦合。
• 含迁移、回滚、双写、定时任务、队列、插件或 hook 编排。
• 含 agent、自动化写配置或写用户目录。
• 用户明确要求深度评审、交叉验证或多评审者。

篇幅很短且风险档位自评为低时，可单代理全流程，但须在「评审覆盖」写明未采用多子代理及原因。

角色划分（推荐三拆）

同一轮内并行派发，每个子代理只使用本技能、同一被评文档路径、同一 review-output-template.md 的字段要求，但各自侧重的七维子集如下；须使用带前缀的发现项编号以便合并：C-F1、X-F1、S-F1 等；合并后主编排者改为全局 F1…。

子代理	代号	侧重维度	必做增量
契约与正确性	C	一致性、正确性、完整性	主路径是否自洽、与上游规格是否冲突、非目标与范围
执行与运维	X	可执行性、可运维性	任务顺序、幂等/清理/回滚、可观测、人工步骤
安全与证据	S	安全性、可验证性	信任边界、写盘与权限、测试与证据是否撑得住结论

两子代理折中： C 负责 一致性+正确性+完整性+可执行性；S 负责 安全性+可验证性+可运维性。

工作流程

主编排者：固定被评文档路径、归档路径、是否三拆或两拆
    │
    ├─ 并行 ─→ 子代理 C：输出带 C- 前缀的发现项草稿 + 覆盖声明
    ├─ 并行 ─→ 子代理 X：输出带 X- 前缀的发现项草稿 + 覆盖声明
    └─ 并行 ─→ 子代理 S：输出带 S- 前缀的发现项草稿 + 覆盖声明（三拆时）
    │
    ▼
主编排者：合并、去重、消解或升级冲突 → 统一 F 编号 → 填一份 review-output-template.md
    │
    ▼
可选：人审终判

同一轮触发： 勿串行等第一个子代理结束再派第二个；并行结束后再合并，缩短总延迟。

交叉验证规则

1. 重叠扫描： C 与 X 都看「可执行性」边角时，若仅一方提出某点，主编排者须快速复核是否应升格或吸收进报告。
2. 独立撞题： 两个子代理对同一位置、同一风险各自给出发现项 → 合并为一条，级别取较高者，在理由中注「双视角一致」。
3. 冲突： 对同一事实结论相反 → 写入「开放问题」或发现项标 [高]，列出双方论据，禁止主编排者无依据强行折中。
4. 覆盖诚实： 各子代理稿中的「评审覆盖」合并进终稿；未读部分取并集，勿丢弃。

子代理任务提示片段

派发时附上相同上下文块，仅替换「你的代号与侧重的维度」：

你已挂载 dev-plan-review 技能。被评文档：[路径]。
你的角色：[C / X / S] — 仅在该角色对应的七维子集上深挖；其他维度若发现致命问题可写，但标注「越权发现」。
输出：按 `references/review-output-template.md` 结构输出草稿，发现项 ID 使用 `C-F1`、`X-F1` 或 `S-F1` 形式；评审覆盖须诚实。
禁止：与其他子代理通稿；仅基于文档与技能独立评审。

主编排者合并清单

• 所有子代理草稿已收齐
• 发现项已去重并完成全局 F1… 映射
• 冲突与双视角一致项已在总体结论或开放问题中体现
• 仅对外交付一份终稿模板，并可选附子代理原始稿为附录

输出与文档模板

对话输出

先给执行摘要（3～6 句）：结论档位、最高严重级别、是否阻塞、是否已落盘及路径。

评审文档

完整正文必须基于 references/review-output-template.md 填写，并保留四个固定二级标题：发现项、开放问题、总体结论、评审覆盖。须包含：被评方案摘要、带 F 编号与维度的发现项表、发现项下的七维索引、总体结论内的决策摘要表与理由、评审覆盖内的阅读与假设及证据与验证表。

禁止只给口头意见而不产出可复制的报告体 Markdown。

若暂无阻塞性发现项：保留「发现项」小节说明未发现阻塞性问题，并在同节或「总体结论 / 评审覆盖-证据」中写明残余风险与建议补做验证。

自检清单

评审过程中或收尾时，按 references/review-checklist-template.md 勾选；勾选结果可贴在报告末尾「附录」或单独文件（如 *-checklist.md）。

参考文件

文件	用途
references/review-output-template.md	报告：被评摘要、F 编号发现项、七维索引、总体结论含决策表与理由、评审覆盖含阅读与证据
references/review-checklist-template.md	七维自检清单，勾选框形式

常见借口

借口	事实
「计划而已，实现时再补测试」	测试策略与风险应对应对齐；无证据不视为通过
「逻辑上没问题」	要求可判定验收条件或状态说明；否则记为中高级模糊
「agent 不会乱来」	Instruction 不是安全边界；须硬门控或可核验约束
「太长略过」	执行者无法还原步骤即阻塞：要求拆分或补全
「性能以后再说」	若触及用户路径或 SLA，列入开放问题或发现项

危险信号

• 安全或资金相关段落出现：大概、应该、差不多、视情况、另行约定、以后人工等不可验收措辞。
• 自动化绕开写路径控制：未定义白名单、扫描或等价硬门控。
• hook、cron、CI、队列任务缺少幂等、清理或超时上界。
• 状态落文件却无锁、原子写、损坏检测或重建说明。
• 测试只证明安装成功或退出码，不断言行为或失败形态。
• 后半段任务依赖前半段未验证假设。

示例

差： 先按章节复述全文，最后说「整体不错」。

好： 直接写发现项，例如：[高] 任务 4：Stop hook 失败后 trigger 文件未定义清理，重入可能双触发……

差： 「子代理会遵守 SKILL，不会写到 skills 外。」

好： [严重] 仅靠文档约束路径不足；须 PreToolUse 白名单或等价拦截及对应测试。

差： 只描述迁移成功后的终态。

好： [高] 回滚未定义：Step 2 写失败后是否维持双写窗口？旧读路径保留多久？

验证

交付前须将下列待勾选框逐项勾为已满足；全部勾选后，方可将本轮评审标为「完成」。

• 已按 references/review-output-template.md 产出完整评审文档（已写入仓库路径，或在回复中附上同等结构的 Markdown 全文）
• 已使用 references/review-checklist-template.md 完成勾选（附于报告附录或单独文件，或说明以等价方式覆盖）
• 对话中含执行摘要，并指向报告路径或注明全文位置
• 输出含四段：发现项、开放问题、总体结论、评审覆盖（发现项可为「未发现阻塞性问题」但必须提及残余风险）
• 七维评审均被显式考虑，无关维已标「不适用」
• 每条发现项含 F 编号、级别、位置、触发条件、影响、可执行建议，并标注主维度（七维之一）
• 报告含 被评方案摘要、发现项表与 七维索引、总体结论内决策摘要表、评审覆盖内证据表（模板结构一致）
• 主路径与失败路径均已被推演或已记录信息不足
• 已审查证据链（测试、验收、监控、回滚或手工验证）
• 若涉及 agent、hook、写盘、生产数据或密钥，已单独给出安全相关结论
• 开放问题一条一事，无合并含糊提问
• 总体结论与最高严重级别一致（严重不得「可直接实现」；高默认不得「可直接实现」除非风险已书面隔离）
• 评审覆盖诚实，未假装已读代码或环境
• 以上验证项已全部满足，本轮交付物符合本技能质量契约
• 若启用多子代理：已并行派发、已合并为单份终稿，处理冲突与双视角一致项，且评审覆盖为并集