review-prd

review-prd · 基于代码事实的产品需求评审

目标是判断：在用户约束内，这份 PRD 是否充分设计了值得做、可用且体验好的产品，能否清楚交接「做什么」与「怎样算完成」，它对代码现状和前置能力的认识是否真实。 评审既检查错误与缺口，也检查有价值的创新和 AI 机会是否被遗漏；不止审文档格式。

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

references/ 相对本文件解析。仓库规则、产品上下文、代码位置、工具和外部依赖在运行时读取，不硬编码目标仓的业务约定。回复语言跟随用户。

边界与参考

• 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
• 区分现状事实、目标能力、用户/平台约束、未证实假设、验收门槛与观察/PoC 基线。新能力尚未实现不是 PRD 缺陷；代码当前行为也不是禁止产品演进的理由。报告指出增量与前置，不擅自把当前实现固化为需求。
• PRD 回答 what / why / 怎样算完成。用户旅程、信息层级、视觉要求、AI 产品行为属于产品设计；内部架构、表结构、端点拆分、模型/算法选型与技术里程碑属于开发计划。UAT 定义角色、场景、预期状态与清晰判据；测试脚本、造数、故障注入、工具及 TC 创建属于测试计划。已给定技术约束、外部产品契约与作为产品能力的评测台可以保留，不能机械按技术词判越界。
• 在可用时读取 prd/references/product-quality.md 校准产品质量规则；采用该模板的文档再按需读 prd/references/prd-skeleton.md。找不到 prd 时继续按本技能的实质标准评审，不要求安装依赖。用户自定义模板或历史 PRD 不因章节名、编号、缺少 TC 或未录入 SPMS 被判不合格。
• UI 评审读取目标仓实际适用的产品/设计规范；只有能看到的材料才支持视觉结论。源码、静态稿、原型与浏览器实测分别标注，不把静态推演写成已验证体验。

1. 锚定输入与审查基线

1. 定位用户指定 PRD、原始诉求、已确认约束、关联 PRD 与必要决策。目标无法唯一确定时询问文件/范围，可以先调查仓库规则；不擅自选一份相邻文档评审。
2. 读取适用的根目录及相关子目录规则、产品与设计上下文。记录 PRD 路径/版本或内容 hash、调查日期、代码仓路径、commit 与 dirty 状态；当前工作树参与调查时明确写出。无 Git 则用可用版本标识；读不到源代码则如实记录证据缺口，继续能做的文档审查。
3. 提取目标、非目标、角色/权限、业务状态、关键旅程、FR/NFR、UAT/验收、依赖、产品决策、分期与终验关系。无需求 ID 时用稳定章节定位，不补造 SPMS key。只读工具可用时核对关联项目/需求与重复立项情况，不把录入状态当实现状态。
4. 将会改变产品选择的现状主张和前置条件列入核实清单：声称已支持、未支持、可复用、无需改动、兼容、已验证及性能数字等。标清它们是事实还是未来目标。
5. 读取 references/report-contract.md，确定报告路径；记录四个审查维度及代码核实、报告写入、回读核验的状态。事实能查就先查，只向用户询问无法从证据推出的产品决定；缺少某项输入时继续不依赖它的审查。

修复效果复审

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

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

$review-prd docs/PRD-login.md，对照 docs/PRD-login.review.md 复审修复效果，逐项记录结果。

2. 编排四个审查视角

先读 references/review-lenses.md 的对应节，再分派。各视角都以用户约束为边界，不为凑问题扩大产品范围。

角色	主责	必须交回的专属结果
facts	代码现状、依赖契约、主张真伪与内部冲突	现状核实矩阵：已有能力、真实增量、行为冲突、未核实项及证据
product	创新、先进性、AI 价值与合理范围	关键产品选择的价值/取舍；有依据的遗漏机会、AI 闭环与前置
experience	可用性、便捷旅程、美观 UI 与状态表达	各角色任务闭环；体验/视觉缺口；界面证据等级
acceptance	SMAR、UAT、需求追踪、分期与终验	目标/场景/需求/验收/UAT 的断链；独立用户价值、计划规模与终验一致性

调度规则

• 有多 agent 工具且当前授权允许时实际启动只读 subagents，主 agent 负责综合裁定和报告单写；不能在同一回答中扮演多个角色后宣称独立复核。简单局部文档可用两位 reviewer 各覆盖两个视角，回报分开说明覆盖与结论。模型继承主 agent，不主动覆盖模型或推理档位。
• 并发数按实际剩余槽位安排，主 agent 也占槽位。只有 4 个总槽位时，先运行 3 个视角，结束后复用空闲 agent 完成第 4 个；更少则分批。工具/授权不允许、用户要求串行时，主 agent 按四个视角顺序审查，如实写执行方式，不能漏掉维度。
• 初轮给 reviewer 相同基线、用户约束和原始材料，不把预设缺陷或别人的结论当答案。每个 reviewer 只读原 PRD 与代码，不能继续派生 agent，也不写最终报告。
• 代码可并行只读；共用浏览器或外部环境由一个操作者采集证据。评审不自动跑迁移、种子、部署、收费模型评测或有副作用的业务操作。必要验证按现有授权执行，做不到则报告缺口。
• 单个 reviewer 失败时重派一次或由主 agent 接管；不能核实的部分进入待核实项，不无限重试。

Reviewer 派发合同

你负责 {facts/product/experience/acceptance}，只读评审，不实现、不改稿、不继续派生 agent。
用户目标及范围：{原始要求、排除、已有产品决定}
PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日期}
必读：{本 SKILL.md、report-contract.md、review-lenses.md 对应节的绝对路径}
相关材料：{规则、产品/设计上下文、已知代码入口、关联 PRD/需求的实际位置}
资源边界：{可读目录、可运行检查、外部查询与浏览器授权}
核实产品主张依赖的实际行为；新功能未实现不算缺陷，现有代码也不是永久产品约束。
交回：范围与基线；候选问题（PRD 定位、场景/触发、影响、证据、最小产品修订、
复核判据、严重度与置信度）；本视角专属结果；待核实/待决定项及所需证据。
没有问题可以返回空 findings。机会提案须说明用户价值与约束，不强制增加功能或实现方案。

3. 主 agent 交叉复核与裁定

1. 逐条阅读支持候选问题的 PRD 段落与原始证据，核对角色、作用域、版本和触发条件。文件/函数存在不等于行为可用，多位 reviewer 一致也不等于事实。
2. 现状核实至少追到 PRD 依赖的用户或外部系统可观察行为：入口/权限、关键业务逻辑、结果与状态反馈；按需求核对租户隔离、分页、重复/冲突、数据保护、失败恢复、AI 权限/预算及依赖。只读到部分链路就标部分核实，不声称端到端可用。
3. 将证据影响传回相关视角：例如事实侧发现模型调用没有当前主体授权，产品侧复核 AI 前置，体验侧复核不可用状态，验收侧复核判据和分期。只复核受影响链路，不借机设计具体调用方案。
4. 按根因与修订动作去重，保留所有实质不同的问题。已确认问题进入 findings，低证据主张进入待核实项；纯偏好不算缺陷，有价值但非必要的产品机会单列，不凑问题数或用总分抵消阻塞。
5. 核对「目标 ↔ 场景 ↔ FR/NFR ↔ 验收 ↔ UAT 状态 ↔ 分期/终验」的一致性。每期要有独立用户价值；承接计划尽量 5–8 个 Milestone，连续性例外 9–10 个须有理由，最多 10 个。PRD 的规模建议不是技术任务表，不能要求其已经拆出 M1…Mn。
6. 结束前核对 PRD 与相关代码是否并发变化；只重审受影响结论，无法收敛则标待核实。收集或停止仍在运行的 reviewer，再交付。

4. 输出评审结果

使用 references/report-contract.md 的完整报告顺序和落盘合同，先列问题，再给总体结论与修订顺序。由主 agent 保存完整报告并回读；空 findings、代码无法访问或结论为「需补证」也要落盘。

报告至少包含：

• 报告头的「评审对象」：原 PRD 的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 apply-doc-review 可仅接收报告参数。
• 按严重度排序且可定位的问题，附用户场景、实际后果、行为级证据、最小产品修订与复核条件。
• 代码现状核实矩阵、关键依赖和待核实项；区分静态代码、现有测试、实际运行与浏览器证据，不把尚待开发的目标报成当前缺陷。
• 四维覆盖及六个产品设计维度的实质结论、SMAR/UAT 与分期终验的断链；不因缺少固定章节或 TC 判错。
• 建议结论 通过 / 需修订 / 需补证，写清阻塞范围与解除条件；有价值的非阻塞机会与修订优先顺序。

评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、UI 已验证或可直接上线。 最终聊天回复给实际报告链接、结论和关键问题/待核实项摘要。写入失败时说明「报告未落盘」并按合同保留完整内容，不能链接不存在的产物。

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

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

判定	条件	下一步
需要修改	结论为「需修订」，或「需补证」且所缺事实/产品决定要写回 PRD	apply-doc-review <本报告路径>：核实意见、补查事实、交互确认决定后修订 PRD
无需修改	结论为「通过」，只剩 P3 或产品增强机会	按 PRD 期次出开发计划：dev-plan <PRD 路径> P1（PRD 未分期时省略期次；已知某期已有计划时给下一期）。想采纳 P3 或增强机会时，可选 apply-doc-review <本报告路径>

所缺证据只能由外部提供、PRD 本身不需改写时，写明缺什么、由谁提供，补齐后用 review-prd <PRD 路径> 复审。仅聊天模式没有报告文件时，说明需先落盘报告才能交给 apply-doc-review。只给出建议命令，不自行启动下一步。

项目状态回写

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

每次实际评审登记独立评审 ID、PRD 版本、覆盖范围、原结论与报告路径；复审关联前轮，保留历史，不因通过改写 PRD 实施状态。台账更新属于已有跟进协议的产物索引，不修改原 PRD。