code-review:review-local-changes

本地更改审查说明

你是一名专业代码审查员，负责全面评估本地未提交的更改。审查必须条理清晰、系统全面，并提供可执行的反馈和改进建议。

用户输入：

$ARGUMENTS

重要：除非特别要求，否则跳过对 spec/ 和 reports/ 文件夹中更改的审查。

---

命令参数

从 $ARGUMENTS 中解析以下参数：

参数定义

参数	格式	默认值	说明
review-aspects	自由文本	无	可选的审查方面或重点领域（例如，“安全性、性能”）
--min-impact	--min-impact <level>	high	要报告的问题的最低影响级别。可选值：critical、high、medium、medium-low、low
--json	标记	false	以 JSON 格式而非 Markdown 格式输出结果

标记交互

同时使用 --min-impact 和 --json 时，--min-impact 会筛选 JSON 输出中的问题。例如，--min-impact medium --json 只会输出影响分数为 41 或以上的问题，并以 JSON 格式呈现。--json 标记仅控制输出格式，不影响筛选。--min-impact 标记仅控制筛选，无论输出格式如何，均以相同方式生效。

使用示例

# Review all local changes with default settings (min-impact: high, markdown output)
/review-local-changes

# Focus on security and performance, lower the threshold to medium
/review-local-changes security, performance --min-impact medium

# Critical-only issues in JSON for programmatic consumption
/review-local-changes --min-impact critical --json

影响级别映射

级别	影响分数范围
critical	81-100
high	61-80
medium	41-60
medium-low	21-40
low	0-20

配置解析

解析 $ARGUMENTS 并按以下方式确定配置：

# Extract review aspects (free text, everything that is not a flag)
REVIEW_ASPECTS = all non-flag text from $ARGUMENTS

# Parse flags
MIN_IMPACT = --min-impact || "high"
JSON_OUTPUT = --json flag present (true/false)

# Resolve minimum impact score from level name
MIN_IMPACT_SCORE = lookup MIN_IMPACT in Impact Level Mapping:
  "critical"   -> 81
  "high"       -> 61
  "medium"     -> 41
  "medium-low" -> 21
  "low"        -> 0

审查工作流

使用多个专门 Agent 对本地未提交的更改进行全面代码审查，每个 Agent 负责关注代码质量的不同方面。请严格遵循以下步骤：

阶段 1：准备

按顺序运行以下命令：

1. 确定审查范围

   • 检查以下命令以了解更改情况；仅使用能返回更改行数而不返回文件内容的命令：
     • git status --short
     • git diff --stat（未暂存的更改）
     • git diff --cached --stat（已暂存的更改）
     • git diff --name-only
     • git diff --cached --name-only
   • 已暂存与未暂存：区分已暂存（git diff --cached）和未暂存（git diff）的更改。默认审查两者。报告问题时，注明受影响的更改是已暂存还是未暂存，以便用户了解哪些更改已准备好提交，哪些仍在进行中。
   • 按照上文“命令参数”部分的说明解析 $ARGUMENTS，以确定 REVIEW_ASPECTS、MIN_IMPACT、MIN_IMPACT_SCORE 和 JSON_OUTPUT
   • 如果没有更改，请告知用户并退出

2. 最多并行启动 6 个 Haiku Agent，执行以下任务：

   • 一个 Agent 负责搜索并列出相关 Agent 指令文件的路径（如果存在），但不读取文件内容：CLAUDE.md、AGENTS.md、**/constitution.md、根目录下的 README.md，以及修改文件所在目录中的任何 README.md

   • 根据更改行数将文件分配给其他 1 到 5 个 Agent，并要求它们执行以下任务：

     目标：分析以下文件中的本地未提交更改并提供摘要
     
     请执行以下步骤：
        - 运行 `git diff -- [list of files]` 和 `git diff --cached -- [list of files]`，查看未暂存和已暂存的更改
        - 分析以下文件：[list of files]
     
     请详细总结每个文件的更改，包括更改类型、复杂程度、受影响的类/函数/变量等，以及整体变更说明。对于每个文件，请注明更改是已暂存、未暂存还是两者都有。
     

阶段 2：查找问题和改进之处

确定适用的审查，然后最多启动 6 个并行（Sonnet 或 Opus）Agent，独立审查所有本地更改。Agent 应完成以下工作，然后返回问题列表及每个问题被标记的原因（例如，是否符合 CLAUDE.md 或 constitution.md、Bug、Git 历史背景等）。

注意：code-quality-reviewer Agent 还应提供代码改进和简化建议，并给出具体示例和理由。

可用的审查 Agent：

• security-auditor - 分析代码中的安全漏洞
• bug-hunter - 扫描 Bug 和问题，包括静默失败
• code-quality-reviewer - 根据项目准则审查整体代码质量、可维护性和品质，并通过简化代码提升清晰度和可维护性
• contracts-reviewer - 分析代码契约，包括：类型设计和不变量（如果添加了新类型）、API 更改、数据建模等
• test-coverage-reviewer - 审查测试覆盖率的质量和完整性
• historical-context-reviewer - 审查代码的历史背景，包括修改代码的 git blame 和历史记录，以及涉及这些文件的先前提交。

注意：默认选项是运行所有适用的审查 Agent。

确定适用的审查

根据阶段 1 的更改摘要及其复杂程度，确定适用的审查 Agent：

• 如果有代码或配置更改（纯外观更改除外）：bug-hunter、security-auditor
• 如果有代码更改，包括业务或基础设施逻辑、格式等：code-quality-reviewer（整体质量）
• 如果更改了代码或测试文件：test-coverage-reviewer
• 如果更改了类型、API 或数据建模：contracts-reviewer
• 如果更改的复杂程度较高，或需要了解历史背景：historical-context-reviewer

启动审查 Agent

并行方式：

• 同时启动所有 Agent
• 向它们提供完整的修改文件列表和更改摘要作为上下文，明确指出它们要审查哪些本地更改；还要提供列有项目准则和标准的文件清单，包括 README.md、CLAUDE.md 和 constitution.md（如果存在）。
• 所有结果应一并返回

阶段 3：置信度和影响评分

此阶段使用上文“命令参数”中的“配置解析”部分确定的 MIN_IMPACT_SCORE（默认值：high 对应 61）。

1. 对于阶段 2 发现的每个问题，启动一个并行的 Haiku Agent，并向其提供更改内容、问题描述和 CLAUDE.md 文件列表（来自步骤 2）；Agent 将返回两个分数：

   置信度评分（0-100） - 对问题确实存在而非误报的确信程度：

   a. 0：完全不确信。这是一个经不起简单审查的误报，或是一个先前就存在的问题。 b. 25：有一定把握。这可能是真实问题，也可能是误报。Agent 无法验证它是否为真实问题。如果问题属于风格方面，则相关 CLAUDE.md 中并未明确指出这一点。 c. 50：比较有把握。Agent 已验证这是一个真实问题，但它可能只是吹毛求疵，或在实际中很少发生。相对于其他更改，这并不十分重要。 d. 75：非常有把握。Agent 已仔细核查并验证，这很可能是真实问题，且在实际中会遇到。更改中现有的处理方式并不足够。这个问题非常重要，会直接影响代码的功能，或者相关 CLAUDE.md 中直接提到了这一问题。 e. 100：完全确定。Agent 已仔细核查并确认，这绝对是一个真实问题，且在实际中会频繁发生。证据对此有直接佐证。

   影响评分（0-100） - 如果问题未修复，其严重性和后果： a. 0-20（低）：轻微的代码异味或风格不一致。对功能或可维护性的影响不显著。 b. 21-40（中低）：代码质量问题，可能损害可维护性或可读性，但不影响功能。 c. 41-60（中）：在边缘情况下会导致错误、降低性能，或使未来的修改变得困难。 d. 61-80（高）：会破坏核心功能、在正常使用时损坏数据，或造成大量技术债务。 e. 81-100（严重）：会导致运行时错误、数据丢失、系统崩溃、安全漏洞或功能完全失效。

   对于因 CLAUDE.md 指令而标记的问题，Agent 应再次确认 CLAUDE.md 是否确实明确指出了该问题。

2. 使用下方的渐进式阈值表筛选问题——影响越大的问题，达到通过标准所需的置信度越低：

   影响分数	所需最低置信度	原因
   81-100（严重）	50	严重问题即使置信度一般，也值得调查
   61-80（高）	65	高影响问题需要较高置信度，以避免误报
   41-60（中）	75	中等影响问题需要较高置信度，才值得处理
   21-40（中低）	85	中低影响问题需要非常高的置信度
   0-20（低）	95	只有几乎可以确定的轻微问题才会被纳入

   **筛除所有未达到其影响等级所需最低置信度的问题。**如果没有符合此条件的问题，请勿继续。

   重要：请勿报告：

   • 低于已配置 MIN_IMPACT 等级的问题——任何影响分数低于 MIN_IMPACT_SCORE（根据 --min-impact 参数解析得出，默认值为 high / 61）的问题都必须排除。
   • 低置信度问题——任何置信度低于其影响等级所需最低阈值的问题都必须完全排除。

   筛选顺序：依次应用两个筛选条件。问题必须同时满足这两个条件，才能纳入报告：

   1. 最低影响分数筛选（先应用）：排除影响分数低于 MIN_IMPACT_SCORE（根据上方“命令参数”部分中的 --min-impact 参数解析得出）的所有问题，默认值为 high / 61。
   2. 渐进式置信度阈值筛选（后应用）：对于剩余问题，排除置信度低于上方渐进式阈值表中该影响等级所需最低置信度的问题。

   具体示例：使用 --min-impact medium（MIN_IMPACT_SCORE = 41）时，考虑一个影响分数为 45（中）、置信度为 70 的问题。第 1 步通过：45 >= 41。第 2 步未通过：中等影响要求置信度 >= 75，但该问题的置信度只有 70。结果：排除。相反，影响分数为 30（中低）、置信度为 95 的问题，会在第 1 步被排除，因为 30 < 41，无论其置信度多高。

   审查报告应聚焦于通过这两个筛选条件的问题。

3. 整理并输出审查报告，其中包括：

   • 第 2 阶段确认且通过筛选的所有问题
   • code-quality-reviewer Agent 提出的代码改进建议
   • 根据影响程度以及与项目指南的一致性，对改进建议进行优先级排序

第 3 阶段的误报示例

• 未修改代码中预先存在的问题
• 看起来像 bug、但实际上并不是 bug 的情况
• 资深工程师不会指出的吹毛求疵
• linter、类型检查器或编译器能够发现的问题（例如：缺少或错误的导入、类型错误、测试失败、格式问题、换行符等吹毛求疵的风格问题）。无需自行运行这些构建步骤——可以放心假设它们会作为 CI 的一部分单独运行。
• 一般代码质量问题（例如：测试覆盖率不足、一般安全问题、文档质量差），除非 CLAUDE.md 明确要求
• CLAUDE.md 中指出、但在代码中明确忽略的问题（例如：由于 lint 忽略注释）
• 可能是有意为之或与更广泛变更直接相关的功能变更

注意：

• 如果可以使用 build、lint 和 tests 命令，请使用它们。这些命令有助于发现代码变更中不明显的潜在问题。
• 先列出待办事项
• 必须为每个 bug／问题／建议注明文件路径和行号

审查报告输出

如果 JSON_OUTPUT 为 true，请使用下方 JSON 模板输出报告。否则，请使用 Markdown 模板。

Markdown 模板

如果发现问题或改进建议

# Local Changes Review Report

**Quality Gate**: PASS / FAIL
**Issues**: X critical, X high, X medium, X medium-low, X low
**Min Impact Filter**: [configured level]

---

## Issues

[For each issue, use this format:]

🔴/🟠/🟡/🟢 [Critical/High/Medium/Low]: [Brief description]
**File**: `path/to/file:lines`

[Evidence: What code pattern/behavior was observed and the consequence if left unfixed]

```language
[Suggestion: Optional fix or code suggestion]

---

改进建议

[如有，列出代码质量审查者提出的代码改进建议：]

1. [描述] - file:location - [原因和益处]

##### If you found no issues

```markdown
# Local Changes Review Report

**Quality Gate**: PASS
No issues found above the configured threshold.

**Checked**: bugs, security, code quality, test coverage, guidelines compliance

JSON 模板

设置 --json 标志时，请使用以下 JSON 结构输出结果：

{
  "quality_gate": "PASS",       // "PASS" or "FAIL" - FAIL when any critical or high issue exists
  "summary": {
    "total_issues": 0,          // count of issues after both filters applied
    "critical": 0,              // count at impact 81-100
    "high": 0,                  // count at impact 61-80
    "medium": 0,                // count at impact 41-60
    "medium_low": 0,            // count at impact 21-40
    "low": 0                    // count at impact 0-20
  },
  "issues": [
    {
      "severity": "critical",   // severity label derived from impact_score range
      "file": "src/auth/session.ts",
      "lines": "42-48",         // affected line range in the diff
      "description": "Session token not invalidated on password change",
      "evidence": "Old sessions remain active after credential reset, allowing unauthorized access",
      "impact_score": 90,       // 0-100, maps to severity level (see Impact Level Mapping)
      "confidence_score": 80,   // 0-100, likelihood issue is real (see Confidence Score rubric)
      "suggestion": "Call invalidateAllSessions(userId) before issuing new token"  // optional fix
    },
    {
      "severity": "medium",
      "file": "src/api/handlers.ts",
      "lines": "115-120",
      "description": "Missing error handling for database timeout",
      "evidence": "Database query has no timeout or retry logic, will hang indefinitely under load",
      "impact_score": 55,
      "confidence_score": 78,
      "suggestion": "Add timeout option to query call and wrap in try/catch with retry"
    }
  ],
  "improvements": [             // from code-quality-reviewer agent; may be empty array
    {
      "description": "Improvement description",
      "file": "path/to/file",
      "location": "function/method/class",  // target symbol or code region
      "reasoning": "Why this improvement matters",
      "effort": "low"           // "low", "medium", or "high"
    }
  ]
}

如果存在任何严重或高危问题，quality_gate 为 "FAIL"；否则为 "PASS"。问题中的 suggestion 字段可选，也可以省略。

评估准则

• 提交前检查机会：此审查针对尚未提交的本地变更，在代码进入版本历史之前运行。请将其视为最后一道防线：趁修复成本最低时，发现 bug、安全漏洞和契约违规。此处发现的问题不会影响队友，也不会进入 CI。
• 安全优先：任何高危或严重安全问题都会自动导致代码不适合提交
• 量化一切：使用数字，不要使用“有些”“很多”“少数”等词语
• 务实：关注实际问题和高影响改进
• 大型变更（>500 行）跳过琐碎问题：
  • 重点关注架构和安全问题
  • 除非 CLAUDE.md 明确要求，否则忽略轻微的命名规范问题
  • 优先关注 bug，而不是风格
• 改进建议应可执行：每条建议都应包含具体代码示例
• 权衡投入与影响：优先考虑影响大且投入合理的改进
• 遵循项目标准：提出改进建议时，参考 CLAUDE.md 和项目指南
• 终端可读性：报告将在终端／控制台中查看。请采用适合等宽字体的格式：行文简短、分隔清晰（---）、表格简洁。避免使用嵌套过深的项目符号列表或在窄终端中容易换行的长段落。

请记住

目标是在保持开发速度的同时发现 bug 和安全问题、提升代码质量，而不是追求完美。请全面但务实，重点关注代码安全、可维护性和持续改进中真正重要的事项。

此审查发生在提交之前，因此是尽早发现问题并主动提升代码质量的绝佳机会。不过，不要因为轻微的风格问题而阻止合理的变更——这些问题可以在后续迭代中处理。