Code Review

---
name: code-review
description: "代码审查技能。对指定文件或变更集执行结构化代码审查，输出问题清单与改进建议，确保符合编码规范与架构决策。"
version: 1.0.0
platforms: [macos, linux, windows]
metadata:
  hermes:
    tags: ["review", "quality"]
    load_mode: on-demand
    model: sonnet
    argument-hint: "[文件路径]"
    user-invocable: true
    allowed-tools:
      - Read
      - Glob
      - Grep
      - Write
      - AskUserQuestion
---

# code-review —— 代码审查技能

## 技能目的

对用户指定的源文件、目录或变更集执行结构化代码审查，
识别规范偏离、架构违约、潜在缺陷与可改进点，输出可操作的审查意见清单，
作为 Pull Request 前置关卡或日常质量把关手段。

## 参数说明

- `[文件路径]`：待审查的文件或目录路径。
  - 若指向单个文件，则仅审查该文件。
  - 若指向目录，则递归审查其下所有源码文件（排除 `node_modules`、`dist`、`build` 等生成产物）。
  - 若提供 Git diff 范围（如 `HEAD~1`），则审查该范围内的变更。

## 分阶段工作流

### 阶段 1：定位与收集

- **输入**：用户提供的 `[文件路径]`。
- **处理**：使用 Read 读取目标文件；若为目录则用 Glob 枚举源码文件并逐个读取。
- **输出**：待审查文件清单及其完整内容快照。

### 阶段 2：加载审查基准

- **输入**：项目规范文档路径。
- **处理**：并行加载 `.claude/docs/coding-standards.md`、`docs/adr/`、`.claude/docs/technical-preferences.md`。
- **输出**：审查基准摘要，包含编码规范要点与相关 ADR 约束。

### 阶段 3：逐项审查

- **输入**：阶段 1 的文件内容与阶段 2 的审查基准。
- **处理**：按以下维度逐项检查：
  1. 命名与格式规范
  2. 架构层级与依赖方向（是否符合 ADR）
  3. 错误处理与边界条件
  4. 安全性与输入校验
  5. 可测试性与覆盖率线索
  6. 性能与资源管理
  7. 可读性与重复代码
- **输出**：问题列表，每条含文件、行号、严重度（阻塞/建议/提示）、说明。

### 阶段 4：生成审查报告

- **输入**：阶段 3 的问题列表。
- **处理**：汇总为 Markdown 报告，按严重度分组，给出具体修改建议与示例代码片段。
- **输出**：审查报告文件，默认写入 `docs/reviews/REVIEW-<时间戳>.md`。

### 阶段 5：反馈与跟进

- **输入**：审查报告草稿。
- **处理**：使用 AskUserQuestion 向用户确认报告是否满足预期，是否需要追加审查范围。
- **输出**：最终报告路径与关键阻塞项摘要。

## 协作协议引用

- 审查报告草稿在写入前必须询问用户："我可以将审查报告写入 [路径] 吗？"
- 不得自主修改被审查的源代码；仅提出建议。
- 涉及多人协作的审查结果，需明确标注是否需要其他 Agent 复核。

## 推荐下一步

- 阻塞项修复后运行 `/code-review [文件路径]` 复审。
- 若审查涉及 Story 验收标准，运行 `/story-done [故事路径]`。
- 若发现范围外变更，运行 `/scope-check [故事路径]`。