/pdlc-review

name: pdlc-review
description: 代码评审（对照设计、自动修复、跑 check、判定能否发布）或文档评审（PRD / 设计 / 测试计划，不写状态机）
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

代码评审

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） --> ⛔ **IRON LAW · 不可违反的硬门禁**

以下规则为**不可协商**的执行约束：

1. **文件必须落盘**：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。 2. **阶段必须落章**：每个阶段完成后必须在状态机 `docs/.pdlc-state/<feature-id>.json` 追加 history，不可跳过。 3. **测试必须存在**：进入 `/pdlc-implement` 前，对应测试必须存在且处于红灯状态。违反则中止。 4. **自检必须执行**：段二自检为强制步骤，不得以"已经很好了"为由跳过。 5. **防循环**：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。 6. **状态必推进**：成功执行某 phase 后 `current_stage` 必须变更。收尾时若发现 `current_stage` 未推进，视为失败并报错，**不得静默返回**（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，`current_stage` 保持不变但必须写 `last_phase_result.ok=false` + `blocked_reason`。

**违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。** <!-- @include-end templates/prompts/iron-law.md --> <!-- @include templates/prompts/noninteractive.md（已内联于下方，无需另读） -->

非交互模式（`--autonomous`）

若本命令的参数含 `--autonomous`，本命令进入**无人值守**模式，按以下规则处理原本需要人应答的交互点。**参数是唯一真源**：不带 `--autonomous` 即为交互模式，一切照旧正常询问用户；绝不回读状态机 `run_mode` 兜底（「掉出 autonomous」是安全的失败方向）。

1. **流程性确认**（如「测试已绿是否继续」「是否覆盖已有文件」）→ **不询问**，按预设默认前进，并把决策追加到状态机 `history[].auto_decisions[]` （写状态机的命令：推进时给状态推进脚本传 `--decision "<确认点描述>=<所选默认>"`，可重复；脚本写成下面的样子）：

   { "point": "<确认点描述>", "chose": "<所选默认>", "at": "<ISO 8601>" }

2. **真需人判断**（PRD 关键取舍、评审「需人工确认」项、真实循环依赖、**测试与设计 / PRD 矛盾**等无法安全默认的点）→ **不猜**。 改测试、改检查命令让它变绿，永远不是「流程性默认」，不能记成 `--decision`：

• `current_stage` 保持不变（不推进）
• 写 `last_phase_result.ok = false` 且 `blocked_reason = "<原因>"`（写状态机的命令：给状态推进脚本传 `--blocked "<原因>"`）
• 末行输出哨兵：`<<<PDLC blocked reason="<原因>">>>`
• 立即结束命令，交还人类
• **守卫拦截也走这一条**：前置守卫（缺设计文档、缺测试、测试没红等）在 `--autonomous` 下拦住本命令时，

不能只输出 ⛔ 就停——同样写 `ok=false` + `blocked_reason`（写明哪条守卫、缺什么）并输出哨兵。 否则状态机里仍是上一阶段的 `ok=true`，循环驱动只看到 `current_stage` 没动，会把「被拦」误报成「卡住」，真实原因丢失。 3. **破坏性操作**（发布 / 部署 / 打 tag / 触发 CI / DROP / force-push 等不可逆·外发操作）→ `--autonomous` **无效**，仍必须人工显式确认。 4. **顺手的 sidecar 产物**（如缺失时创建 `CHANGELOG.md`、补全文档 PDLC-TRACE 的创建时间等本阶段职责内、可安全默认的辅助改动）→ 视为流程性默认，**直接做并记入 `auto_decisions[]`**；这类改动不新增外部副作用，不属破坏性操作。

> 进入 autonomous 模式时，在状态机顶层写 `run_mode: "autonomous"` 仅供留痕（复盘区分人工 vs 循环产出）。 <!-- @include-end templates/prompts/noninteractive.md -->

对指定的服务或应用进行全面的代码评审。

先分流：代码评审还是文档评审

• 评审对象是**文档**（参数是 `.md` 等文档路径，或明说评审 PRD / 设计 / 测试计划 / 部署手册）→ 直接跳到下文「文档评审」一节。

**文档评审不写状态机**：它是阶段内的质量关卡，不是主链路上的一个阶段——写了会把功能的 `current_stage` 改成 `review`、`next_step` 改成 `pdlc-ship`，等于宣称代码已评审。下文的代码评审守卫也不适用

• 其余（功能ID、缺陷ID、服务 / 模块名）→ **代码评审**，从下面的前置检查开始

PDLC 前置检查（必须执行，不可跳过）

1. 从用户输入中提取功能 ID 或功能名称关键词。输入是缺陷 ID（`B` 开头，`/pdlc-fix` 的下一跳）时， 读 `docs/.pdlc-state/<缺陷ID>.json` 与 `docs/04_testing/defects/` 下对应的缺陷报告，评审对象是这次修复改动的代码 2. **检查实现代码是否存在**：在项目的源码目录下搜索与该功能相关的源代码文件（非测试文件）。源码目录按项目实际布局确定 （如 `src/`、`app/`、`lib/`、`backend/`、`frontend/`、`packages/*/` 等），不要只看某一种布局； 已有状态机时，优先看其 history 里 `impl` / `fix` 阶段记下的 `produced` 路径 3. **检查测试是否通过**：找到对应的测试代码并运行，确认测试处于**绿灯状态**（全部通过） 4. **未找到实现代码** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的实现代码。
   评审必须基于已有的代码实现。请先运行：
   👉 /pdlc-implement <目标>

5. **测试未通过** → 输出以下信息后**立即停止，不继续执行**：

   ⛔ PDLC 守卫：「<功能名>」的测试未全部通过，无法进行评审。
   请先确保所有测试通过后再提交评审：
   👉 /pdlc-implement <目标>（修复失败的测试）

6. **检查通过** → 确定功能ID（输入即 ID 时直接用；否则从相关设计文档或 PRD 中提取；缺陷修复用缺陷ID），继续执行

评审流程

1. **阅读设计文档**: 先阅读 `docs/02_design/` 对应子目录下的相关设计文档

• 有分批评审记录（`docs/07_reviews/code/<功能ID>-*-batch-review.md`，实现阶段按任务分批时写的）→ 一并读：

「已修复」的不重复报；「待最终评审」的每一项都要在本次评审里处理——修掉，或写进报告的需人工处理表，不能悄悄漏掉 2. **阅读编码规范**: 阅读 `docs/00_standards/coding/` 目录了解编码规范（未命中 → 报告里提示 `consider /pdlc-standard add coding/<topic>`） 3. **检查代码实现**: 对照设计文档逐一检查实现是否符合 4. **检查测试覆盖**: 确认测试是否充分覆盖 5. **代码质量自动检查与修复**（必须执行）：

• 按 `/pdlc-lint check` 逻辑运行项目 lint 工具
• 若存在可自动修复的问题，按 `/pdlc-lint fix` 逻辑自动修复
• 记录修复前后的问题数变化

评审检查项（逐项检查，发现问题立即修复）

**先判断适用性**：下面的清单按 Web 服务写成，不是每个项目都有接口、数据库或页面。 开始前按项目类型（Web 服务 / CLI 工具 / 库 / 桌面应用 / 数据脚本等）与本次改动范围，逐项判断是否适用：

• 适用 → 正常检查，勾选 `[x]` 或记为问题
• 不适用 → 标 `[—] 不适用：<一句话理由>`（如「无 HTTP 接口」「本次改动不涉及数据库」）。不适用项**不算未通过**，也不进自动修复
• 拿不准是否适用 → 按适用检查

设计一致性（对照设计文档）

• [ ] 每个 API 接口的 URL、方法、参数是否与设计文档一致
• [ ] 数据库表结构、字段名、类型是否与 DB 设计一致
• [ ] 响应格式是否符合项目约定的统一格式（以设计文档 / 编码规范为准，如 `{ code, message, data }`）

代码质量

• [ ] 命名是否规范（变量/函数/类遵循项目命名约定）
• [ ] 是否有重复代码可提取为公共方法
• [ ] 错误处理是否合理（不吞异常、不用空 catch、有意义的错误信息）
• [ ] 日志是否充分（关键操作有日志、不打印敏感信息）

安全检查

• [ ] SQL 注入：是否使用参数化查询/ORM，无字符串拼接 SQL
• [ ] XSS：用户输入是否转义后再输出
• [ ] 权限控制：接口是否有鉴权，敏感操作是否有权限校验
• [ ] 敏感数据：密码是否加密存储、Token 是否有过期机制、日志不含敏感字段

性能检查

• [ ] 数据库查询是否有 N+1 问题
• [ ] 列表接口是否有分页
• [ ] 是否有不必要的全表扫描（缺失索引）
• [ ] 大数据量操作是否有批处理

测试完备性

• [ ] 单元测试覆盖率是否达标（覆盖率达标线**以项目配置为准**：优先取 `docs/00_standards/test-commands.yml` 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 `quality-targets.yml`；两者都没有时按 >= 80% 兜底。）
• [ ] 核心业务路径是否有完整的测试
• [ ] CHANGELOG 是否已更新

自动修复（评审中发现的问题，能修则修）

对以下类型的问题**直接修复代码，不仅仅记录**（只修适用项里发现的问题——标为不适用的检查项，一律不据此改代码； 例如项目没有列表接口，就不会去「补分页」）：

1. **lint 问题**：运行 lint fix 自动修复格式、规范问题 2. **命名不规范**：自动重命名为符合项目约定的名称 3. **缺失错误处理**：自动补充 try-catch / 错误码返回 4. **缺失日志**：在关键操作处自动添加日志语句 5. **SQL 注入风险**：自动改写为参数化查询 6. **XSS 风险**：自动添加输出转义 7. **缺失分页**：自动为列表接口补充分页逻辑 8. **缺失 CHANGELOG**：自动追加变更条目。条目格式 `- <简要描述>（<功能ID 或缺陷ID>）`；`[未发布]` 里已有同一 ID 的条目就不再追加（`/pdlc-ship` 按 ID 去重）

**不可自动修复的问题**（记录到评审报告，标记为需人工处理）：

• 架构层面的设计问题
• 业务逻辑的正确性争议
• 需要重大重构的性能问题

评审报告生成

> ⚠️ **必须创建文件，不可仅在对话中输出。**

**【必须创建文件】** 在 `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>
  - 评