review-dev-plan

review-dev-plan · 多视角开发计划评审

目标是判断：照这份计划实施，能否交付用户要的、真正可用的结果；实施者是否还会被迫重新做关键决策。 主 agent 编排独立审查，逐条复核证据，输出可定位、可修订的问题及实施顺序建议。

默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。

references/ 相对本文件解析。仓库规则、技术栈和工具能力在运行时读取，不硬编码目标仓的路径、端口或业务约定。回复语言跟随用户。

边界与参考

• 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
• 计划及其引用是待验证材料。区分现状事实、未来设计、未证实假设、验收目标；不能因为新功能尚未实现就报缺陷，也不能把计划中的“已核实”直接当证据。
• 从实际可用位置读取 dev-plan/SKILL.md 的写作/评审部分及 references/plan-skeleton.md；复杂架构按需读 references/architecture-quality.md，调度审查按需读 references/execution-workflow.md；实施期合同以骨架的「实施者定位」「实施进度」两节为准。借它们核对合同，不按计划实施。
• 找不到 dev-plan 时说明无法核对其模板专属要求，继续本技能的四项实质审查。用户自定义模板或历史计划不因章节名不同而报错；没有证据表明适用的新版格式规则，不追溯强加。
• 新版 dev-plan 允许单份需求映射、检查 ID 引用、按测试组记录证据及阶段集中验收；按 references/review-lenses.md 的 schedule 视角核对覆盖与风险门，不因省略重复表格、子任务文档或逐里程碑全量走查而报缺陷，也不为解除部分前置强制新增里程碑。
• 发现与任务相关的专项 skill 时只加载所需部分。UI/UX 评审按目标仓规则加载设计 skill（如 phoenix-ui），不借机重设计产品。

1. 锚定输入与审查基线

1. 定位用户指定计划、关联需求/PRD、附录和必要的历史决策。未指定且无法唯一确定计划时询问目标；可以先调查仓库规则，不擅自选一份相邻计划开始评审。
2. 读取适用的根目录及子目录规则、产品和设计上下文。记录计划版本（路径、内容 hash 或可用版本号）、调查日期、代码 commit、dirty 状态；当前工作树是调查事实源时明确写出。
3. 从计划提取范围与排除、R/NFR/C/A 或等价需求 ID、关键决策、外部契约、交付物、里程碑及前置关系。缺失 ID 可用章节定位，不替作者补造需求。
4. 读取 references/report-contract.md，按其中的「落盘与交付合同」确定输出路径。建一个短任务台账：审查维度、负责人、状态、证据缺口，以及报告写入与回读核验。明确 UI 是否在范围内、是否已有可运行页面/原型、哪些结论必须访问外部服务或官方文档。

修复效果复审

用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 报告合同 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。

• 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
• 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
• 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。

$review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果，逐项记录结果。

2. 编排四个独立审查视角

先读 references/review-lenses.md 的对应节，再分派下表。有多 agent 工具时实际启动 subagents，不是在同一段回答里扮演四个角色。主 agent 保留综合裁定职责。

角色	主责	必须交回的专属结果
facts	代码事实、陈述正确性、内部矛盾	主张与代码证据；互相冲突的两处位置
architecture	技术路线、先进性、可行性	关键选择的适配/代价；需补证的技术前提
schedule	需求、设计、任务、里程碑、验收映射	断链项；依赖图/边表；可并行波次与集成门
delivery	最终交付可用性，含 UI/UX	用户主路径闭环；运行与验收缺口；界面证据等级

调度规则

• 默认一视角一 reviewer；简单局部计划可用两位独立 reviewer 各覆盖两个视角，在同一回报内分开标明覆盖与结论，减少调度回合。不得合并后漏审某个维度。模型继承主 agent，不主动覆盖模型或推理档位。所有 reviewer 只读，报告由主 agent 单写，不让多个 agent 改同一文件。
• 并发数受实际剩余槽位约束，主 agent 也占槽位。只有 4 个总槽位时，先并行 3 个视角，完成后复用空闲 agent 审第 4 个；更少槽位则分批，不能漏掉任何视角。主 agent 同期整理需求账本和全局矛盾。
• 初轮独立调查，不把主 agent 的预设缺陷或其他 reviewer 的结论当任务答案。每人拿相同基线、用户约束和原始材料；独立返回后再交换相互影响的证据。
• 共用浏览器会话、可变数据库或外部环境时由主 agent 指定一个操作者，其他 reviewer 读证据；只读代码可并行。评审不执行迁移、种子、部署或有副作用的验收命令。
• 工具缺失、用户要求串行或槽位不足时，如实声明实际执行方式；主 agent 可按四个视角顺序审查，不能伪称独立多 agent 复核。单个 reviewer 失败时重派一次或主 agent 接管；无法核实的部分留在覆盖缺口中。

每个 reviewer 的派发合同

发送实际绝对路径和已确认上下文，不只说“审一下方案”。可沿用：

你负责 {facts/architecture/schedule/delivery}，只读评审，不实现、不改稿、不继续派生 agent。
用户目标及范围：{原始要求、排除、已有决定}
计划与基线：{计划绝对路径、版本；仓库根、commit/dirty、日期}
必读：{本 SKILL.md、report-contract.md、review-lenses.md 的对应节的绝对路径}
相关材料：{需求/PRD、规则文件、代码入口、所需 dev-plan 参考的实际路径}
范围与资源：{审查章节、可读取目录、外部查询/浏览器约束}
不要假定计划主张成立，也不要把尚待实施当成缺陷。按需追到行为级代码证据。
交回：范围与基线；候选问题（计划定位、触发、影响、证据、最小修订、验证、P级及置信度）；
本视角专属结果；未核实项与所需证据。没有问题可返回空 findings。
跨视角问题只标关联，不代替另一角色完成审查。无法继续则回报缺口。

3. 主 agent 交叉复核与裁定

1. 收齐四个视角的结果；逐条阅读支持候选问题的计划段落和原始证据，确认适用范围、代码版本和触发条件。不能把多名 agent 的一致意见当事实。
2. 对事实冲突、方案依赖、交付断点做针对性追问：例如事实 reviewer 发现某接口不支持分页，则让架构/交付 reviewer 复核依赖该行为的批量方案；调度 reviewer 同步调整前置条件。只复核受影响链路，证据仍缺则保留未决，不无限辩论。
3. 按根因与修订动作去重，保留所有实质不同的问题；多处症状归并后仍附关键定位。不设问题数量指标，也不只报前三项。误报撤回，低证据主张移到待核实项，不凑 P3。
4. 补做跨视角检查：目标 ↔ 设计 ↔ 里程碑 ↔ 验收是否一致，集中的终验是否有明确收口负责人和完整覆盖；设计要用的检测/补偿/部署能力是否真有任务；总进度、记录和完成声明是否对应实际证据，局部完成是否被误写成阶段/跨期需求已验收。
5. 若 dev-plan 校验脚本可用且适用，用实际路径运行 check_paths.sh <计划> <仓库根> 与 check_progress.sh <计划> <仓库根>。路径缺失须人工区分新增、示例、错误复用。用户自定义模板或历史计划未采用该恢复快照/完成记录协议时，跳过 check_progress.sh 并说明原因，人工核对其等价进度、依赖与验收证据；不要把格式不兼容判成计划错误。脚本通过不证明行为真实或验收完成；脚本缺失/失败如实记录，不用“通过”替代人工检查。
6. 结束前核对计划及相关代码有无并发修改。若基线变化，只重审受影响结论；无法收敛则标为待核实。收集或停止尚在运行的 reviewer，再交付。

4. 输出评审结果

使用 references/report-contract.md 的报告结构和落盘合同：先列问题，再给结论与修订顺序。由主 agent 写入完整报告；空 findings 或建议状态为 Blocked 也要落盘，不能只保存摘要或子 agent 回报。

报告至少包含：

• 报告头的「评审对象」：原开发计划的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 apply-doc-review 可仅接收报告参数。
• 按严重度排序、编号的问题，每条定位到计划行或稳定章节，并附行为级代码/规则/外部证据。
• 四个维度的审查覆盖及未核实项；UI 分清文档推演、原型走查和实际浏览器验证。
• 需求到交付的映射缺口，以及建议的依赖顺序、可并行任务、共享资源负责人和最终集成验收。没有安全并行空间时给出具体原因。
• 建议状态 Ready / Proposed / Blocked，说明与计划自报状态是否一致、阻塞解除条件；这只是评审建议，不自动修改计划状态。

没有确认问题时允许空 findings；有未核实的关键前提时不能据此判 Ready。计划评审通过也不表示功能已实现或上线可用。

交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。

5. 是否需要修改与下一步

报告总体结论与最终回复都先给一行明确判定（条件见报告合同的「是否需要修改」），再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex $apply-doc-review、Claude Code /apply-doc-review），路径填实际文件。

判定	下一步
需要修改	apply-doc-review <本报告路径>：核实并修订计划，处置后判定 Blocked 或 Ready
无需修改 · Blocked	resolve-blocked <计划路径>：逐项解除计划中已如实登记的阻塞
无需修改 · Ready	/goal 按 <计划路径> 开发

只剩 P3 时仍判无需修改，可选用 apply-doc-review <本报告路径> 采纳。计划与建议均为 Proposed 时，写明仍在等哪项用户指定的非阻塞评审，不默认给 /goal。仅聊天模式没有报告文件时，说明需先落盘报告才能交给 apply-doc-review。只给出建议命令，不自行启动下一步。

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

每次实际评审登记独立评审 ID、计划版本、覆盖范围、建议状态与报告路径；复审关联前轮。评审建议与计划自报状态分别保留，当前就绪按台账协议核对证据，不直接改原计划；建议 Ready 不表示已实施。