| name | pdlc-review |
| description | 代码评审 + 文档评审 |
| argument-hint | <功能ID | PR 描述> |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash |
| layer | 2 |
| stage | review |
| produces | ["docs/07_reviews/**"] |
| requires | [] |
| next_step | pdlc-ship |
| terminal_state | review_done |
| recommended_model | sonnet |
| recommended_effort | medium |
代码评审
对指定的服务或应用进行全面的代码评审。
PDLC 前置检查(必须执行,不可跳过)
- 从用户输入中提取功能名称关键词
- 检查实现代码是否存在:在
backend/ 和 frontend/ 下搜索与该功能相关的源代码文件(非测试文件)
- 检查测试是否通过:找到对应的测试代码并运行,确认测试处于绿灯状态(全部通过)
- 未找到实现代码 → 输出以下信息后立即停止,不继续执行:
⛔ PDLC 守卫:未找到与「<功能名>」相关的实现代码。
评审必须基于已有的代码实现。请先运行:
👉 /pdlc-implement <目标>
- 测试未通过 → 输出以下信息后立即停止,不继续执行:
⛔ PDLC 守卫:「<功能名>」的测试未全部通过,无法进行评审。
请先确保所有测试通过后再提交评审:
👉 /pdlc-implement <目标>(修复失败的测试)
- 检查通过 → 提取功能ID(从相关设计文档或 PRD 中),继续执行
评审流程
- 阅读设计文档: 先阅读
docs/02_design/ 对应子目录下的相关设计文档
- 阅读编码规范: 阅读
docs/00_standards/coding/ 目录了解编码规范(未命中 → 报告里提示 consider /pdlc-standard add coding/<topic>)
- 检查代码实现: 对照设计文档逐一检查实现是否符合
- 检查测试覆盖: 确认测试是否充分覆盖
- 代码质量自动检查与修复(必须执行):
- 按
/pdlc-lint check 逻辑运行项目 lint 工具
- 若存在可自动修复的问题,按
/pdlc-lint fix 逻辑自动修复
- 记录修复前后的问题数变化
评审检查项(逐项检查,发现问题立即修复)
设计一致性(对照设计文档)
代码质量
安全检查
性能检查
测试完备性
自动修复(评审中发现的问题,能修则修)
对以下类型的问题直接修复代码,不仅仅记录:
- lint 问题:运行 lint fix 自动修复格式、规范问题
- 命名不规范:自动重命名为符合项目约定的名称
- 缺失错误处理:自动补充 try-catch / 错误码返回
- 缺失日志:在关键操作处自动添加日志语句
- SQL 注入风险:自动改写为参数化查询
- XSS 风险:自动添加输出转义
- 缺失分页:自动为列表接口补充分页逻辑
- 缺失 CHANGELOG:自动追加变更条目
不可自动修复的问题(记录到评审报告,标记为需人工处理):
- 架构层面的设计问题
- 业务逻辑的正确性争议
- 需要重大重构的性能问题
评审报告生成
⚠️ 必须创建文件,不可仅在对话中输出。
【必须创建文件】 在 docs/07_reviews/code/ 下创建评审记录:
- 文件名格式:
<功能ID>-<功能名>-review.md(如 F20260326-090000-user-auth-review.md)
- 文档顶部必须包含 PDLC 追溯头:
<!-- PDLC-TRACE -->
<!-- 功能ID: F20260326-090000 -->
<!-- 功能名称: user-auth -->
<!-- 阶段: 评审 -->
<!-- 前置文档: docs/02_design/api/F20260326-090000-user-auth-api.md -->
<!-- 创建时间: 2026-03-26T10:30:00 -->
- 报告内容格式:
## 评审总结
- 评审时间:<ISO 8601>
- 评审范围:<涉及的文件数和代码行数>
- 问题总数:X 项(阻塞: X / 严重: X / 一般: X / 建议: X)
- 自动修复:X 项
- 需人工处理:X 项
## 自动修复记录
| # | 问题类型 | 文件 | 修复内容 |
|---|---------|------|---------|
| 1 | lint | src/xxx.ts | 修复 XX 规则违规 |
## 需人工处理
| # | 严重程度 | 问题描述 | 建议方案 |
|---|---------|---------|---------|
| 1 | 阻塞 | XXX | 建议 XXX |
## 评审检查项结论
- [x] 设计一致性:通过
- [x] 代码质量:通过(X 项已自动修复)
- [ ] 安全检查:X 项需人工确认
- 修复后验证:自动修复完成后,重新运行全部测试(命令取自
docs/00_standards/test-commands.yml),确认修复未引入新问题
- 测试通过 → 评审完成
- 测试失败 → 回滚修复,将问题标记为需人工处理
- 写
last_phase_result:checks 取自真跑 test-commands 的 unit/coverage/lint 退出码,不用自检冒充;
退出码三态语义与「命令跑不了 = yml 过期信号」见下方 check 命令规则
--autonomous 下的收尾判定(呼应非交互契约):
- 「需人工处理/需人工确认」表中存在阻塞级项 → 不推进:
last_phase_result.ok=false + blocked_reason="评审存在阻塞级待人工项" + 输出 blocked 哨兵,交还人类
- 仅有非阻塞级人工项 → 记录在案并正常推进到
review_done
要求
- 问题按严重程度分级:阻塞 / 严重 / 一般 / 建议
- 能修的问题直接修复,不仅仅指出问题
- 修复后必须验证测试仍然通过
评审目标: $ARGUMENTS
文档评审
对指定的文档进行质量评审,检查完整性、一致性和可操作性。发现问题直接修复,而非仅列出建议。
文档评审检查项
完整性
一致性
可操作性
规范性
文档自动修复规则(发现即修,不仅记录)
- 缺失章节:对照模板自动补充,内容根据文档已有信息合理推断
- PDLC 追溯头缺失或不完整:自动补全缺失字段
- 术语不一致:统一为文档中首次出现的术语,全文替换
- 模糊表述:自动改写为具体、可度量的描述
- 表格格式问题:自动修复空列、对齐问题
- Markdown 语法错误:自动修复标题层级、列表缩进
- 交叉引用路径错误:检查引用的文件是否存在,不存在则标注警告
- 缺失示例:为 API 接口自动补充请求/响应示例
不可自动修复的问题(记录到评审报告):
- 业务逻辑的正确性争议
- 需要与产品确认的需求歧义
- 涉及跨文档架构调整的问题
文档评审工作流程
- 识别文档类型:判断文档属于 PRD / API 设计 / DB 设计 / 架构设计 / 测试计划 / 部署手册
- 加载对照物:
- 加载对应的模板(
templates/ 目录)
- 加载前置文档(从 PDLC-TRACE 中获取路径)
- 如是设计文档,同时加载 PRD 进行交叉比对
- 逐项检查:按上方检查项逐一执行
- 自动修复:发现问题直接修改原文档
- 【必须创建文件】生成评审记录:在
docs/07_reviews/doc/ 下创建评审记录
- 修复后仅复查一次(确认修复未引入新问题),不再递归修复。若复查仍发现问题,记录到评审报告的「需人工确认」中