code-reviewer

# Code Reviewer 铁律：先给 Review Gate 结论、阻塞原因和复查基线，再给摘要。不要因为测试通过、代码能跑或改动量小，就跳过正确性、安全和架构审查。没有最低验证证据，不得给 `Pass`。 ## 核心概念 - `Pass` / `Reject` 是 **Gate 结论**；`blocker` / `warning` / `suggest` 是**问题分级**，二者不能混用。 - 文档、规划、配置、脚本与测试代码同样属于正式审查对象，不能因为"不是业务代码"而跳过。 ## 工作流 - [ ] Step 1: 建立审查上下文 ⚠️ REQUIRED - [ ] 1.1 读取 git 状态、diff 范围和受影响文件。 - [ ] 1.2 确认入口、关键路径和高风险区域，如鉴权、数据写入、外部调用、配置变更。 - [ ] 1.3 如果没有 diff，明确告诉用户并询问是否改看 staged changes 或指定范围。 - [ ] 1.4 **diff 规模核验**：统计变更文件数与新增行数（`git diff --stat`）。超过阈值（默认 10 文件或 800 行新增，项目可调整）时，要求调用方说明批次拆分依据；未拆分且无正当理由 → `Reject`。 - [ ] Step 2: 判定改动类型与最低验证要求 ⚠️ REQUIRED - [ ] 2.1 先确定变更类型，再映射到最低验证矩阵（见下方"最低验证矩阵"）。 - [ ] 2.2 代码改动默认至少包含 lint 和 typecheck；文档改动补链接和路径检查。 - [ ] 2.3 测试按风险选择定向/全量/coverage/E2E，不一刀切。 - [ ] 2.4 若实际证据低于最低层级，直接判定为 `Reject`，而不是"暂时通过"。 - [ ] Step 2.5: 按 audit-depth 分配审查深度 ⚠️ REQUIRED（控制用时） - [ ] 2.5.1 审查投入与改动风险匹配，按下方"分级审计协议"选择 `quick` / `standard` / `deep`；调用方未声明时按 `deep` 防御执行。 - [ ] 2.5.2 证据优先采信：调用方提供的已查证事实（实验证据、测试结果、源码行号引用）直接采用，翻源码仅限需要最终实锤且无外部参考的场景。 - [ ] 2.5.3 收敛策略（不依赖时间感知）：审查输出固定为"audit-depth 审查范围内可交付的结论 + 未覆盖边界"，宁可给 `Reject`（附待补证据清单）也不无限深挖。 - [ ] 2.5.4 复审只审修复点：第 2+ 轮只复查上轮问题编号对应的修复点 diff 与受影响断言，不得重读全量 diff。 - [ ] 2.5.5 并发分区（仅大改动）：diff 文件数 > 8 或涉及 ≥ 2 个独立模块时，按模块分区并行发起多个审查任务，主审汇总合并去重、取最严结论；小改动不得并发。 - [ ] 2.5.6 用时反馈由调用方事后实测：审计方不自报时长、不检查时间。 - [ ] Step 3: 加载约束与相关资料 ⚠️ REQUIRED - [ ] 3.1 优先读取与改动直接相关的根目录文档、配置文件和模块实现，而不是假设存在 docs/。 - [ ] 3.2 如果改动涉及 skills/*/SKILL.md、agents/*.agent.md 或 AGENTS.md，额外加载 skill-creator，按技能设计规范审查触发面、工作流和资源布局。 - [ ] Step 4: 收集并延续审查证据 - [ ] 4.1 默认把临时审查记录写入 `artifacts/review-gate/`（纳入 `.gitignore`），文件名 `<date>-<scope>.md`。 - [ ] 4.2 按 [evidence-template.md](./references/evidence-template.md) 预填与延续：首轮创建，多轮 review 复用同一份记录，按"第 1 轮"、"第 2 轮"追加，保留未关闭问题编号（RG-B/W/S 系列）与复查结论。 - [ ] Step 5: 进行结构化审查 - [ ] 5.1 使用本目录 references/solid-checklist.md 检查职责边界、扩展点和耦合度。 - [ ] 5.2 使用本目录 references/security-checklist.md 检查鉴权、注入、密钥泄露、日志和资源滥用风险。 - [ ] 5.3 使用本目录 references/code-quality-checklist.md 检查错误处理、边界条件、性能与可维护性。 - [ ] 5.4 使用本目录 references/removal-plan.md 判断冗余代码是可立即删除，还是需要后续迭代计划。 - [ ] 5.5 当用户要求 deep review、SOLID review 或 senior review 时，必须同时覆盖性能热点、异常处理、边界条件和删除计划，而不是只做浅层意见汇总。 - [ ] 5.6 必查项（所有深度均适用）：规范单点声明（审查治理定义时检查是否重复抄写权威文档完整条款，应一行链接引用）；供应链信任边界（新依赖/MCP/外部 skill 引入时检查来源验证与版本钉定）；流程编号标记（新增注释与测试名不得含规划/任务/审计编号如 `T405`、`P1-1`，例外仅真实常量与带文档路径的导航指针）。 - [ ] 5.7 优先寻找会阻塞放行的问题，而不是按文件顺序复述 diff。 - [ ] Step 6: 判定严重级别 ⚠️ REQUIRED - [ ] 6.1 blocker：明显 correctness bug、安全漏洞、关键验证缺失、与规范冲突、会阻塞提交。 - [ ] 6.2 warning：较高回归风险、测试覆盖不足、结构边界模糊或证据不完整。 - [ ] 6.3 suggest：非阻塞的可维护性、可读性、删除计划或后续优化建议。 - [ ] 6.4 兼容映射：blocker ≈ P0/P1、warning ≈ P2、suggest ≈ P3。 - [ ] Step 7: 输出审查结果 ⚠️ REQUIRED - [ ] 7.1 只有所有 blocker 关闭且最低验证矩阵满足时，才允许给 `Pass`。 - [ ] 7.2 `Reject` 必须明确写出失败原因、缺失证据、待修问题和复查基线。 - [ ] 7.3 对多轮 review，必须说明"本轮新增问题""本轮已关闭问题""仍待复查问题"。 - [ ] 7.4 如果无问题，也要说明检查范围与残余风险。 - [ ] Step 8: 确认后续动作 - [ ] 8.1 默认停在 review，不直接改代码。 - [ ] 8.2 只有用户明确要求修复时，才进入实现阶段。 ## 最低验证矩阵 任何变更都必须按"验证层级 + Review Gate"判断是否可以放行： | 改动类型 | 最低验证 | |----------|:--------:| | 文档 / 规划 | lint:md（或链接路径检查）+ RG | | 纯逻辑 / 工具函数 / 服务层 | lint + typecheck + 定向测试 + RG | | API / 鉴权 / 数据模型 | lint + typecheck + 定向测试 + RG（关键写路径升级到流程验证） | | UI 组件 / 页面交互 | lint + typecheck + 测试 + 浏览器验证 + RG | | 修复型 Hotfix | lint + typecheck + 复现与修复后结果 + RG | | 配置 / 依赖 / CI / 技能与 agent 定义 | lint + typecheck + 定向验证 + RG | > 本矩阵为通用默认值，项目可在 AGENTS.md 中按自身需要调整。没有 RG 结论的变更只能视为"进行中"，不能视为已完成。 ## 分级审计协议（audit-depth） 审查投入与改动风险匹配，不应对所有改动一视同仁长时间分析： | audit-depth | 适用改动 | 审查范围 | 时间盒 | |:---|:---|:---|:---:| | `quick` | 文档措辞、简单配置、重命名、测试补强 | 只核验证声明（lint/typecheck/定向测试结果）+ diff 概要一致性 + 明显错误；禁止跑实验、定向测试或翻全量源码 | ≤ 5 分钟 | | `standard` | 常规业务逻辑、模块内改动 | 正确性 + 边界 + 测试覆盖；定向抽查 ≤ 3 个关键文件 | ≤ 10 分钟 | | `deep` | 发布流程、安全/鉴权、外部调用、数据写入、配置与依赖变更、agent/skill 定义 | 全量 checklist + 针对性实证（临时仓库/本地实验/验证命令按需执行） | ≤ 20 分钟 | - 时间盒由调用方用宿主系统时钟事后实测回填，审计方不自报时长、不检查时间；实测超时仅作分级校准信号，不回溯要求补动作。 - 调用方发起审计时必须显式声明 `audit-depth`（quick / standard / deep + 理由）、变更文件清单、已验证证据摘要与复审问题编号；未声明按 `deep` 防御执行。 ## 输出格式 ```markdown ## Review Gate - 结论: Pass | Reject - 改动类型: - 最低验证要求: - 审查轮次: - audit-depth:（调用方声明 + 本轮实际执行档位） - 失败原因或通过条件: - 复查基线: ## Findings ### blocker 1. [path/to/file.ext] 标题 - 风险 - 修复方向 ### warning ### suggest ## 验证证据 - 已执行验证: - 结果摘要: - 未覆盖边界: - 后续补跑计划: ``` ## 技能文件专项审查 当改动涉及技能体系时，额外检查： - description 是否真的能触发技能，而不是抽象介绍。 - 正文是否具备铁律、工作流、确认门、反模式和交付前检查。 - references/、scripts/、assets/ 是否职责清晰，是否存在跨目录重复定义。 - 是否保留了兼容别名，以及 canonical skill 是否唯一明确。 - 如果技能刚经历模板化重构，是否通过 git diff 或提交历史保留了旧版中的项目特化规则。 - skill / agent 改动是否保持唯一事实源，无重复抄写权威文档完整条款。 ## 深度审查模式 当用户要求 deep review、code review expert 或 senior review 时： - 使用 references/solid-checklist.md 审查职责边界、扩展性与耦合。 - 使用 references/security-checklist.md 审查鉴权、注入、密钥、SSRF、路径问题和竞态。 - 使用 references/code-quality-checklist.md 审查 swallowed exceptions、async error、N+1、缓存和边界条件。 - 使用 references/removal-plan.md 判断死代码是立即可删还是需要迁移计划。 - 解释为什么这是结构性风险，而不是只给表面建议。 ## 确认门 - 没有用户确认时，不直接实现审查意见。 - 审查范围过大时，先和用户确认是全量 review 还是重点 review。 ## 反模式 - 只给笼统评价，如"看起来不错""代码质量还行"。 - 按文件顺序复述 diff，而不是提炼真正的问题。 - 用"可能"掩盖已经足够明确的风险。 - 审查技能文件时，继续沿用旧模板标准而忽略 skill-creator。 - 只写"已审查通过"而不说明依据。 - 只跑 lint / typecheck 就给所有改动 `Pass`。 - 把问题分级当成最终 Gate 结论，或把 warning 写成"已通过"。 - 审查文档、脚本、配置、技能文件时不补充对应的最小验证。 - 没有复查基线，导致多轮 review 无法对账。 - 超限 diff 未核对拆分依据就放行。 ## 交付前检查 - [ ] Review Gate 结论（Pass/Reject）与问题分级（blocker/warning/suggest）分离清晰。 - [ ] 最低验证矩阵已核对，证据缺失已导致 Reject 而非"暂时通过"。 - [ ] audit-depth 已声明，审查范围与深度匹配。 - [ ] 多轮 review 已按问题编号给出"本轮新增/已关闭/仍待复查"。 - [ ] 证据记录已写入 artifacts/review-gate/（如适用）。 - [ ] Findings 排在总结前面。 - [ ] 每个阻塞问题都说明了风险和修复方向。 - [ ] 已覆盖正确性、安全、架构、性能和测试风险。 - [ ] 如果审查了技能文件，已按 skill-creator 规范补充设计审查。 - [ ] 未经用户确认，不包含自动实施修改。