quality-review：独立代码质量审查

目的：找出“能跑但丑陋、业余、不专业”的代码，以及过度设计。本 skill 只输出问题，不修改代码。

步骤

1. 准备输入并判断语言
   • 范围：只审查代码与实现相关的配置文件。所有以 . 开头的目录（如 .claude/、.git/、.github/、.idea/）及其内容一律忽略，包括 skill、工具配置和 IDE 文件。
   • 运行 git diff HEAD --stat -- ':(exclude,glob)**/.*/**' 与 git diff HEAD -- ':(exclude,glob)**/.*/**'，把 diff 保存为临时目录（宿主提供的临时目录，没有则用仓库外的系统临时目录）下的 review-input.diff。
   • 追加未跟踪的文件时，同样跳过路径中含 . 开头目录的文件（git ls-files --others --exclude-standard 的结果用 grep -v '/\.' 且 grep -v '^\.' 过滤）。
   • 限定范围：用户指定了文件或目录时，上述命令只针对这些路径（在 -- 后追加路径，未跟踪文件同样按路径过滤）。未指定时，先看 --stat 的文件列表；明显不属于本次任务的改动（如其他未提交的工作）不纳入，并在“审查覆盖范围”中列出被排除的文件。
   • 规模提示：diff（含未跟踪文件）超过约 2000 行时，在报告开头写明“改动规模过大，建议拆分后再审”，并在“审查覆盖范围”中说明哪些部分只做了抽查。阈值只作提示，不阻断审查。
   • 根据改动文件后缀判断语言：.java 加载 references/java.md，.ts、.tsx 加载 references/ts.md。两种都有时两份都加载；其他语言只用本文件的检查清单。
   • 找出项目说明文件（如 CLAUDE.md、AGENTS.md、CONTRIBUTING.md、README）。项目约定以这些文件为准，优先于 references 中的默认规则。
   • 找出本次改动对应的已确认方案（方案文档的路径，或用户指定的文件），并确定本次审查对应的切片编号。方案只存在于对话中时，把用户确认的方案原文保存为同一临时目录下的 plan.md，不加入实现过程的解释。找不到方案时问用户；用户确认没有方案的，在“方案对照”中写明“无方案，未对照”。小改动（见第 2 步）找不到方案时不问，直接写“无方案，未对照”。
   • 复审：本次是修复上一轮审查问题之后再审时，可以做增量复审，仍由 subagent 独立执行。范围是：
     • 上一轮报告的每条问题是否已修复；
     • 与上一轮 review-input.diff 相比有变化的文件，审它们的完整 diff（生成本次 diff 前，先把上一轮的文件改名为 review-input.prev.diff）。 出现以下任一情况，改为完整审查：
     • 方案有修改；
     • 有变化的部分涉及对外接口、数据模型、事务、并发或权限；
     • 有变化的部分超过约 300 行；
     • 找不到上一轮的报告或 diff。 报告的“审查覆盖范围”中注明“增量复审”以及基线（上一轮报告的路径）。 上一轮处置为“不改”的问题不再原样提出；有新证据时可以重提，须引用上一轮该条的位置并写明新证据是什么。
   • 作者自述的盲区：本切片跑过 risk-walkthrough 时，把其“未检查的地方”一节原文保存为同一临时目录下的 unchecked.md。没有跑过的，在“审查覆盖范围”中写明“无作者自述盲区”。
   • 不要把实现过程中的对话、推理或“为什么这样写”的解释传给下面任何一路。

2. 启动审查

   • 路线 A（subagent）、路线 C（P3C）和第 4 步的可执行检查在同一轮并行发起，互不依赖。
   • 小改动：审查范围内的 diff（含未跟踪文件）不超过约 300 行、且只涉及一种语言时，不启动 subagent，由主流程按“检查清单”直接审查（同样不参考实现对话），并在“审查覆盖范围”中注明“小改动，非独立上下文审查”。路线 B、C 的规则不变。
   • 路线 B（ocr）不自动运行。宿主提供结构化提问工具（如 Claude Code 的 AskUserQuestion）时必须用它发起确认；没有时在文字中提问，并在用户回复前停下等待，不得先运行。问题写明本次改动规模（文件数、行数），以及耗时和 token 消耗会随规模增长（参考：约 1 万行 diff 需要 10 分钟左右、数百万 token）；选项为“运行 ocr”和“不运行”，不运行为默认推荐项。只有用户选择“运行 ocr”才运行；选择“不运行”、取消或未回应时，在“审查覆盖范围”里写明“ocr 未运行（用户未确认）”。
   • 用户在本轮之前已经明确同意过的，可以直接运行，但要在报告中写明依据。

   路线 A：审查 subagent 用宿主提供的独立上下文子代理（如 Claude Code 的 Agent 工具、general-purpose 类型）执行，prompt 包含：

   • 宿主不支持子代理时，由主流程在不参考实现对话的前提下自行审查，并在“审查覆盖范围”中注明“非独立上下文审查”。
   • diff 文件的绝对路径
   • 方案文件的绝对路径，以及本次审查对应的切片编号
   • unchecked.md 的绝对路径（有时），并明确指示：先逐条核查其中列出的地方，再做其余检查
   • 本 skill “检查清单”一节的全部内容
   • 对应语言的 references/*.md 全文
   • 项目说明文件的路径，并要求审查开始前完整阅读
   • 输出格式（见“输出格式”）
   • 明确指示：只读，不修改文件；没有问题就直接写“无”，不要凑数，不要夸奖
   • 明确指示：围绕 diff 审查；为核实检查项（如是否已有同类实现、调用方如何使用）可以搜索和打开其他文件，不做与检查项无关的浏览

   路线 B：open-code-review（需用户确认后才运行） 运行 ocr review --format json --audience agent --exclude '.*/**,**/.*/**' -o <临时目录>/ocr.json。--exclude 排除所有以 . 开头的目录，避免审查工具文件。它审查工作区的其余改动，结果是 JSON。耗时通常超过命令的前台超时，应以后台方式运行（如 Claude Code 的 run_in_background），完成后再读取结果。

   • 主流程读取 JSON 的 comments 数组，每条含 path、start_line、end_line、severity（high/medium/low）、category、content。
   • ocr 的 tool_calls.failure_details 里可能有读取不存在文件的失败记录（模型引用了已删除或改名的文件）。这些失败不影响结论，但若某条 comment 只基于不存在的文件，应在报告中忽略并注明。
   • 未安装 ocr 或未配置模型端点时会直接报错。报错时在报告中注明“ocr 未运行”及原因，不要静默跳过。

   路线 C：P3C（仅 Java 改动） 运行 scripts/p3c-check.sh（相对本 skill 目录）。它检查工作区中变更的 .java 文件，包括未跟踪的新文件。

   • 退出码 0 无违规且无覆盖缺口；2 有违规；3 无违规但有文件未能解析（覆盖缺口）；1 为脚本或工具错误。
   • 两类结果可能同时出现，此时退出码为 2，但输出中会同时列出违规与未解析文件。必须同时阅读两部分输出，不能只看退出码。
   • 未解析文件属于 P3C 的覆盖缺口，需要在报告的“覆盖范围”中列出，并由 subagent 人工审查。
   • P3C 2.1.1 基于 PMD 6.15.0，无法解析 record 等较新语法，这类文件会出现在未解析列表中。
   • 脚本独立下载并校验 SHA-256 后运行，不依赖项目自身的构建配置。

3. 检查清单（subagent 逐条核对）

   方案对照（最先做，按决策对照）

   • 找出 diff 中引入的决策：业务规则、数据和判定的来源（含本地副本、映射、默认值）、新增的类型或抽象、对外接口和契约、数据模型、外部调用、用户可感知的行为、失败处理策略、新增的配置和依赖、范围变化。
   • 每个决策对应到方案的条目编号或原文位置。结构类决策（模块、类型、接口）按方案的结构骨架核对；来源类决策按方案约束中的真源核对；新增的抽象、依赖和组件按方案的“抽象与依赖预算表”核对。实现某个条目所需的机械代码（组装、字段、转换、日志、测试等）归入该条目，不单独标注。
   • 方案中没有的决策，标注 方案外：文件:行号、决策内容（一句话）、最接近的方案条目（没有就写“无”）。即使决策看起来合理或必要，也要标注。
   • 与方案不一致的（同一条目，但实现方式、数据来源或范围不同），标注 与方案不符，并引用方案原文。
   • 本次切片的条目在 diff 中找不到实现时，先在现有代码中搜索：
     • 已有实现且与方案一致的，注明位置，不标注；
     • 已有实现但与方案不一致的，标注 与方案不符；
     • 确认仍缺失的，标注 未实现；
     • 无法确认的，标注 未核实，并写明缺少什么证据。

   可读性与结构

   • 命名是否清楚、与周边风格一致；是否有误导性的名字
   • 方法是否超过 50 行；职责是否单一；嵌套是否过深（能早返回的没有早返回）
   • 是否有重复逻辑，且重复达到值得抽取的程度（抽象不是越多越好）
   • 注释是否在复述代码；公共 API 是否有文档注释

   是否用了专业做法

   • 是否手写了项目已用框架或标准库已有的能力
   • 错误处理：吞异常、空 catch、捕获过宽的异常类型、日志里打印敏感信息
   • 语言特定的规则见对应的 references/*.md

   过度设计（重点检查）

   • 只有一个实现的接口或抽象类
   • 无人调用的参数、配置项、扩展点
   • 为“以后可能”准备的通用层、注册表、插件机制
   • 能用一个函数或一条 SQL 解决却拆成多层的代码
   • 绕开项目已有的脚本、模块或工具另建一套，或同一能力被重复实现

   测试

   • 测试验证的是行为，还是实现细节
   • 测试能否抓到错误：对关键判断和异常路径自问“去掉这段逻辑，会有哪个测试失败？”，没有就标为测试缺口
   • 期望值从哪来：断言的值应来自需求、方案条目或已有测试；照着实现当前的输出抄下来的期望值（快照、硬编码的计算结果）只证明代码没变，不证明代码对，标为测试缺口，并写明应从哪里取期望值
   • 验收测试是否走了真实能力：被验收的那部分能力（文件系统、数据库、解析器等）被 mock 掉的，不算验收证据；单元测试内按项目约定 mock 依赖不在此列
   • 测试是否沿用项目约定的测试基础设施，没有引入与之冲突的替代品

   数据与安全

   • 数据库变更是否遵守项目的迁移与字段注释约定
   • 是否有硬编码的密码、token、连接串
   • 事务边界是否正确，循环中是否有逐条查询（N+1）
4. 可执行检查（由主流程在第 2 步与审查同时启动，结果附在报告末尾）
   • 从项目说明文件和构建配置（如 Makefile、package.json、Gradle、Maven）中找出静态检查、lint、类型检查命令，按改动涉及的语言运行。
   • 默认不运行测试。测试结果引用实现阶段或 risk-walkthrough 的验证结果，并注明来源；被引用的结果必须是在最后一次代码改动之后运行的。没有这样的结果时写“测试未运行（没有当前代码的结果）”，并建议运行。用户要求时才运行测试。
   • 找不到对应命令时注明“项目未配置”；未运行的检查要注明原因。
5. 汇总
   • “方案对照”的结果单独成节，放在报告最前面，按方案条目归类，不与质量问题合并。
   • 走路线 A 时，主流程汇总只核验各路问题的证据（文件、行号、引用的代码是否属实），不重新完整审查。核验不属实的问题剔除，并在“审查覆盖范围”中注明剔除了哪些、原因是什么。
   • 合并三路结果，去重（同一文件、相近行号、同一问题视为一条）。
   • 每条标注来源：subagent、ocr、p3c，两路以上都提到的问题优先级提高。
   • 按严重度排序，分级标准：
     • 严重：行为错误、回归、数据丢失或不一致、安全问题、测试声称覆盖但实际抓不到该错误；
     • 建议：方案外的设计、过度设计、测试缺口、错误处理缺失、违反项目约定；
     • 细节：命名、注释、文档与代码不一致等不影响行为的问题。 拿不准时就低不就高，并在描述里写明升级条件。P3C 的规则按 references/java.md 的采纳表判定是否纳入，未采纳的不列入问题。
   • 对每条问题，给出“现在的写法”和“更简单或更专业的写法”，但不替用户直接修改代码。
   • 与 risk-walkthrough 的重难点相关的问题，注明关联。
   • 如果某一路失败或未运行，在“审查覆盖范围”里写明。

输出格式

## 方案对照
- 方案：<方案文件路径>
- `文件:行号` 方案外｜与方案不符｜未实现｜未核实：决策内容 → 最接近的方案条目
## 严重问题（必须修）
- `文件:行号` 问题描述 [来源：subagent / ocr / p3c，可多个]
  - 现在：...
  - 建议：...
## 建议问题（应该修）
## 细节问题（可选）
## 可执行检查结果（实际运行的命令及结果）
## 审查覆盖范围（subagent / ocr / p3c 各自是否运行、未覆盖的内容）

每条问题必须有文件和行号。没有问题的分类直接写“无”。主流程把汇总结果交给用户，由用户决定修改哪些，并把报告保存为临时目录下的 review-report.md，供复审作为基线。用户答复后，在 review-report.md 每条问题末尾追加处置：处置：改 或 处置：不改（理由）；用户没说理由的写“未说明”。