---
name: code-review
allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh pr list:*), mcp__github_inline_comment__create_inline_comment
description: 当用户要求进行 PR 代码审查或评审意见输出时使用此技能，遵循项目规则并用 gh 获取必要信息。
---

# 代码评审技能

## 项目概览入口
- 项目定位、技术栈与目录入口请阅读：`../references/project-overview.md`

## 目的与触发
- 目的：输出高信号的 PR 评审结论，按“数据库 → 契约 → 后端 → 前端 → 测试 → 文档”的顺序发现缺陷/风险，并遵守项目规则。
- 触发：用户要求审查 PR 或输出评审意见。

## 快速守则
- 工具默认可用；仅在必要时调用，每次调用需有明确目的。
- 只标记高信号问题（必然错误/明确规则违反），避免主观或低信号建议。
- 关闭/草稿/WIP/无需评审或已由 Claude 评论的 PR：直接停止。
- 结论用中文，先列问题再给疑问或假设；需引用具体文件行号。
- 评审顺序固定为：数据模型与迁移 → API 契约 → 后端状态机/业务 → 前端契约消费 → 权限与隔离 → 测试与文档。
- 前一层存在阻断问题时，后一层只做快速扫视，不深挖样式或重构建议。
- 适用规则优先级固定为：`docs/` > `AGENTS.md` / `CLAUDE.md` > skill；发现冲突时按项目规则停止并上报，不自行裁决。
- **不要按规模建议拆 PR**（文件数 / commit 数 / diff 行数都不是拆分信号）。只在以下两种情况下提"应拆分"：(1) PR 包含 ≥ 2 个**无关主题**——commit message 一句话讲不清干啥；(2) **高风险路径**（`prisma/schema/**` / `docs/standards/**` / `CLAUDE.md` / `AGENTS.md` / `.gitea/workflows/**` / API 契约面 / 性能热路径）和其他改动混在一起。**单一主题的大 PR 接受**，不要消耗 reviewer 时间在"建议拆小一点"上。详见 `CLAUDE.md` § "PR 拆分准则"。

## 按目标分支调整审查深度（必须）

PR 的目标分支决定 review 模式，不同模式关注点不同：

| 目标分支 | 模式 | 关注点 | 行为 |
|---------|------|-------|-----|
| `develop` (L2) | **硬规则 block** | 契约面文档缺失、迁移文件 > 1、明显逻辑错、测试缺失 | 硬规则违反直接 `block`；软规则（命名/可读性）只评论不阻断；目标是快速通过让 test 环境快速看到改动 |
| `staging` (L3) | **批次审** | 一批 feature 整体的交付质量、跨模块影响、数据迁移合理性 | 关注本批次合并到一起后的整体风险，不再深究单个 commit 的细节（L2 已审过）；输出"批次摘要 + 风险点 + 建议人工 approve / 修复 / 拆分" |
| `production` (L4) | **发布风险审** | 回滚预案、灰度策略、不可逆改动、上线时机 | 重点是"上线后如果出问题怎么办"——回滚 SQL 是否可写、灰度比例、监控告警是否就位；不再审代码细节 |

## 本地前置模式（commit 前自检）

跑 `bash scripts/dev/ai-review-local.sh` 在 commit 前过一遍 7 维度审视，把方向性问题（漏文档 / 段名悬空 / 高风险路径漏单独 PR / 测试覆盖缺口）暴露在推 PR 之前。

| 维度 | 跟 PR runner 的差异 |
|---|---|
| **触发** | 本地手动，不依赖 PR / Gitea |
| **diff 来源** | `git diff origin/develop...HEAD`（默认）/ `--staged` / `--working` |
| **输出** | stdout 轻量文本（verdict + 维度警告 + findings + action）+ `/tmp/ai-review-local.json` |
| **exit code** | pass=0 / risk=1 / fix=2 / block=3，方便 hook / 脚本判断 |
| **Schema** | 跟 PR runner 共用 `scripts/ops/ai-review-schema.json`（单源） |
| **何时跑** | git-main `3. 提交` 阶段先于 `/simplify`；触碰契约面 / 高风险路径 / >10 文件 PR 强烈推荐；小改动 / 文档 hotfix 可跳过 |

**顺序口诀**：ai-review-local 先（架构纠偏）→ /simplify 后（细节打磨）→ commit。先纠方向性问题，后打磨细节，避免 simplify 修完代码再发现方向错。

**判断逻辑**：
1. `gh pr view <PR> --json baseRefName` 拿到目标分支
2. 按上表选择模式
3. 后续的 Findings/Risks/Gaps/Verdict 输出按对应模式聚焦

## 高信号标准
- 必然编译/解析失败（语法、类型、缺失引用等）。
- 必然错误的业务/逻辑/安全问题，与输入无关。
- 明确的规则违反，且可引用具体条款（限同路径或父路径）。
- 违反模块事实源：文档、schema、DTO、返回结构、状态机之间存在明确冲突。
- 缺少组织隔离、权限校验、外键/唯一约束、完整资源返回等高返工成本问题。
- 排除：风格/质量吐槽、依赖特定输入的猜测、未验证的可能性、linter 会提示的事项。

## 工作流
1) 预检可评审性  
   - 用 `gh pr view <PR> --comments` 等确认是否关闭/草稿/WIP（如 `WIP:` / `[WIP]` 前缀）/无需评审/Claude 已评；若是，停止。

2) 收集适用规则与事实源  
   - 列出根目录及变更文件所在目录与父目录中的 `AGENTS.md`、`CLAUDE.md`（仅路径）。
   - 按变更路径定位相关模块文档：优先 `docs/modules/{module}/01-prd.md`、`04-state-machine.md`、`05-ui-interaction-spec.md`、`06-data-model.md`、`07-api.md`、`09-test-scenarios.md`。
   - 若入口文档与 `docs/` 冲突，以 `docs/` 为准，并将冲突本身作为评审结论输出。

3) 获取 PR 概览  
   - 用 `gh pr view`/`gh pr diff` 获取标题、描述、变更范围。
   - 按变更路径判断是否涉及数据库、后端、前端、文档、测试中的哪些层。
   - 检查 PR 描述是否至少说明：改动摘要、影响范围、验证方式；缺失时记为 `Gaps`。

4) 分层审阅（按顺序，不要一上来只盯前端）
   - CLAUDE.md 合规检查：仅考虑同路径或父路径 CLAUDE.md。
   - 只对高信号问题展开，必要时跨文件验证。
   - 检查项统一以 `references/review-checklist.md` 为准，按其中的预检项、阻断级问题、各层重点检查和协作效率原则执行。

5) 验证问题  
   - 确认问题真实、范围正确，CLAUDE.md 适用性正确；无法确认则丢弃。

6) 输出与评论  
   - 有问题：用 `mcp__github_inline_comment__create_inline_comment` 逐项内联，避免重复。小改动可附建议块，大改动给修复思路。  
   - 无问题：用 `gh pr comment`（若提供 `--comment`）输出：
     ```
     ## Code review

     未发现阻断问题。已检查事实源一致性、关键缺陷与入口规则适配。
     ```
   - 总结时优先输出：
     1. Findings（阻断/高优先级问题）
     2. Risks（非阻断但上线风险高）
     3. Gaps（缺测试、缺文档、缺权限、缺契约校验）
     4. Verdict（`block` / `needs-fix` / `pass-with-risk` / `pass`）

## 禁止事项
- 对关闭/草稿/WIP/无需评审/已由 Claude 评论的 PR 继续评审。
- 提出低信号、主观、未验证或已被 linter 覆盖的问题。
- 忽略 `docs/`、`AGENTS.md`、`CLAUDE.md` 的作用域与优先级。
- 跳过数据库/API 层，直接沉迷于 UI 细节、命名偏好或重构建议。
- 在事实源冲突未确认前，自行替用户选择“以代码为准”或“以文档为准”。
- 把超大 PR 当作普通 PR 做细碎审查，而不先要求拆分或标记评审风险。

## 注意（内联链接格式）
- 必须使用完整 git sha，示例：  
  `https://github.com/<owner>/<repo>/blob/<full_sha>/path/to/file.ts#L10-L15`
- 仓库名需匹配当前仓库；文件名后用 `#`；行范围 `L[start]-L[end]`；上下各至少 1 行上下文。