review-code

代码审查

审查目标并报告发现。每条发现都按严重程度（发生时的危害）、可能性（不良路径实际运行的频率）和综合两者得出的是否值得修复结论进行评级；若值得修复，还需提供高层次的修复建议。此技能仅报告问题；除非用户之后明确要求，否则绝不修改代码。

确定目标

从参数中选取目标，忽略任何标志。未指定目标时，默认为 diff。

1. diff（默认） — 当前分支上的本地工作：将未提交的编辑、尚未推送的提交和已经推送的提交一并审查。以基分支的分叉点为基准，而不是以该分支自己的远程分支为基准；否则，提交一旦推送，就会从差异中消失。包含未跟踪的文件，因为普通差异不会包含它们。
2. pr <number>（或 PR URL；单独使用 pr 表示当前分支的 PR）— 审查 GitHub PR：审查其差异以及足以判断意图的 PR 上下文（标题、描述、基分支）。如果 GitHub CLI 不可用，请说明并回退到 diff。
3. <base>...<head> — 审查该提交范围。
4. all / codebase — 审查整个代码库。说明实际能够覆盖的范围，并优先审查入口点、核心逻辑和最近修改的文件。注明跳过的内容。
5. <path> — 将审查范围限定为作为参数传入的文件或目录。

对于差异、PR 或提交范围，审查已更改的行以及足够的上下文（调用方、相关函数），以便判断问题。即使错误只因已更改的行而暴露，也属于审查范围。

在哪里运行审查

默认在当前会话中进行。使用 --sub 时，在子 Agent 中运行完整审查，并原样转交其报告——适用于 all / codebase 或大型差异，因为阅读文件会使会话内容膨胀。如果运行环境没有子 Agent，请说明并在当前会话中进行审查。

第二意见

使用 --second-opinion 时，还需获取另一个 Agent 的审查意见：在 pi 中使用 pi，或在 pi 中使用 Claude Code。

• 先启动。 在后台对同一目标运行 second-opinion 技能，然后在不等待结果的情况下照常审查。即使使用 --sub，主会话也要启动该任务，因为子 Agent 启动的后台任务可能会在子 Agent 退出时终止。如果该技能不可用，请说明并独自审查。

• 原样附加。 在报告后添加一条 --- 分隔线和 ## Second Opinion (<agent>) 小节，纳入另一个 Agent 的审查内容。将其标题级别下调一级（## → ###），使其成为嵌套内容；其余内容一律不改。不要合并、去重或重新评定其发现。如果任务失败，请在该处写明错误；保留自己的审查结果，并跳过最终结论。

• 作出最终判断。 任一审查都可能有误，包括你自己的子 Agent。以另一条 --- 分隔线和 ## Final Call 小节结尾，判断哪些发现确实值得修复：

  • 将两份审查中描述同一问题的发现配对。
  • 对任一审查评为 Yes 或 Judgment call 的每条发现，以及两份审查评级不同的每条发现，都要根据代码中引用的 file:line 进行核实。不要盲目采信任何一方，也不要把意见一致当作正确的证明。
  • 对每条发现给出 Fix、Optional 或 Skip 结论，并用一个从句说明理由。跳过误报（例如误读代码、位置错误或无法运行的路径），并说明原因。
  • 不要在此处添加新发现。

  | # | Finding | Source | Call | Reason |
  |---|---------|--------|------|--------|
  | 1 | <short title> | Main #2, Second #1 | Fix | <why> |
  | 2 | <short title> | Second #3 | Skip | <false positive: why> |
  

审查重点（按优先级排序）

1. 正确性 — 逻辑错误、差一错误、nil/null 解引用、条件判断错误、竞态条件、未处理的错误、API 使用不当、边界情况处理失效。
2. 安全性 — 注入、缺少授权/身份验证、代码中包含机密、不安全的反序列化、路径遍历、未验证的输入。
3. 数据与资源 — 泄漏（文件描述符/内存/goroutine）、无界增长、缺少事务边界、N+1 查询。
4. 性能 — 不必要的内存分配、热点路径上的 O(n²)、循环中的阻塞调用。
5. 代码库适配性 — 为仓库已解决的问题另建一套模式（HTTP 客户端、错误处理风格、配置）、逻辑放错层，或代码量与其实现的功能不成比例。尽量保持精简：方法少、参数简单，把复杂性隐藏在内部。判断新抽象是否必要时，尝试删除它：如果删除后复杂性消失，它只是转发层；如果复杂性会重新分散到各个调用方，它就发挥了作用。
   • 不要使用不必要的 Go interface。 精简的实现应是方法少的具体类型，而不是使用 interface 关键字。只有在存在两种真实实现，或真实依赖无法在测试中运行（第三方 API、远程服务）时才声明接口。只有单一实现的接口属于间接层。
6. 可维护性 — 重复代码、死代码、命名不清、缺少必要测试。仅当这些问题造成实质影响时才报告；不要用风格问题凑数。
7. 测试 — 单元测试过多是负担，不是优势。指出主要测试模拟/伪造行为而非真实行为的测试、会导致任何重构都失败的实现细节测试，以及增加维护成本却未能发现新错误的冗余用例。优先选择针对真实组件的少量测试（集成式测试、内存数据库、真实 HTTP 处理器），而不是大量依赖 mock 的测试。默认不要要求增加单元测试；仅在发现真实错误路径时才要求。重构后，针对已变为内部实现的部分所写的测试应删除，而不应与新测试并存。如果仓库已使用 testify，指出手写的 if got != want { t.Fatal(...) } 代码块。

不要凭空捏造问题。如果代码没有问题，就明确说明。优先报告少数有充分把握的问题，而不是大量推测性问题。

对每项发现评级

严重程度 — 问题路径执行时造成的影响：

• 严重 — 数据丢失/损坏、安全漏洞、常见路径上崩溃、影响用户或资金的错误结果。
• 高 — 现实情况下可能出现的错误结果或崩溃；需要满足某些前提条件的安全问题。
• 中 — 行为退化、性能回归，或罕见路径上的正确性错误。
• 低 — 风格、可读性、不会影响功能的轻微低效。

测试问题的评级应依据其掩盖的风险（未验证的真实路径），而不是测试本身的影响。

发生可能性 — 触发条件实际出现的频率：

• 高 — 正常使用或常见输入就会触发。
• 中 — 不常见但现实中可能出现的输入/时序/配置。
• 低 — 需要罕见、恶意或几乎不可能出现的情况。

是否值得修复 — 根据严重程度 × 发生可能性确定，并结合修复成本调整：

                    Likelihood
Severity     High           Medium         Low
Critical     Yes            Yes            Yes
High         Yes            Yes            Judgment call
Medium       Yes            Judgment call  No (note only)
Low          Judgment call  No             No

• 是 — 建议修复；提供修复方案。
• 视情况而定 — 说明权衡（修复成本与收益），并给出建议；提供修复方案。
• 否 — 提醒注意即可；省略修复方案，或仅用一句话说明。

修复成本 — 提供修复方案时进行评级：

• 微不足道 — 几行代码、一个文件，无需设计变更。
• 较小 — 局部修改，工作量不到一小时。
• 中等 — 涉及多个文件或需要新增测试。
• 较大 — 重构、设计变更或高风险迁移。

如果修复成本为微不足道，应将“视情况而定”上调为“是”；如果相较于收益，修复成本较大或风险较高，则应下调为“否”。偏离矩阵建议时，说明原因。

报告格式

以 ## Summary 部分开头：先列出要点，然后按值得修复的程度排序，列出所有发现的表格（Yes 排在前面），接着列出严重程度。然后添加 ## Findings 部分，每项发现单独成块。每个位置都必须是你实际阅读过的 file:line。如果没有值得报告的问题，则省略表格和 ## Findings。

对于 diff、pr 或范围，添加一个 Net effect 要点：只评估代码库的结构健康状况，不评估功能价值。新功能或能力本身绝不代表有所改进。权衡变更移除或简化的内容与新增的内容。如果调用方需要了解的内容更少，且变更集中在一处，则结构有所改善；如果增加了浅层级，或将同一关注点分散到多个调用方，则结构有所退化。若没有具体证据支持任一方向，默认判定为 Neutral。

## Summary
- **Reviewed:** <target> — <N files, what was covered>
- **Verdict:** <one line: overall health + count of worth-fixing findings>
- **Net effect:** Improves | Neutral | Degrades — <one-line reason> (diff/pr/range only)

| # | Finding | Severity | Likelihood | Worth fixing | Fix effort |
|---|---------|----------|------------|--------------|------------|
| 1 | <short title> | High | High | Yes | Small |
| 2 | <short title> | Low | Medium | No | — |

然后：

## Findings

### 1. <short title>
- **Location:** `path/to/file.ext:42`
- **Category:** correctness | security | resources | performance | codebase-fit | maintainability | tests
- **Severity:** High — <why this impact>
- **Likelihood:** High — <what triggers it>
- **Worth fixing:** Yes
- **Issue:** <what is wrong and what goes wrong as a result>
- **Fix:** <high-level approach, not a full patch>
- **Fix effort:** Trivial | Small | Medium | Large — <one clause on what the fix touches>

常见注意事项

• 不要把测试数量等同于质量。 PR 即使包含大量基于 mock 的单元测试，仍可能没有测试到关键行为。应根据测试锁定的真实行为来评估测试，并指出过度依赖 mock/fake 的测试会带来维护成本。