# Code Review

> 执行代码审查、PR review、复查，或在处理未解决 review threads、发 review 评论、request changes、approve 前必须使用。 审查范围覆盖 GitHub PR diff、本地变更、相关源码、测试覆盖、项目规范与既有评论。 当用户以方案文档（PLAN.md）配合 PR 发起 review 时，额外核对实现与方案一致性，并在 review 阶段回写方案。 回写方案包括同步版本锚点，以及在实现更优或方案过期时主动询问是否更新方案。 默认只输出对话草稿，仅在明确授权后发布评论或回写方案。

- Skill: `zhuozhuocrayon/code-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhuozhuocrayon/code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuozhuocrayon/code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhuozhuocrayon (https://skillmd.com/u/zhuozhuocrayon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhuozhuocrayon/code-review

---


# Code Review

## 0x01 定位

`code-review` 负责审查 PR 或代码变更的正确性、兼容性、可维护性与发布风险。

默认只在对话中输出 review 草稿，不发布到 PR。

GitHub 写操作必须得到用户明确授权，包括评论、approve、request changes 和 dismiss review。

唯一例外：用户触发 review 后，针对已确认修复的既有未解决 review thread，可以自动 resolve。

## 0x02 权限门禁

### a. GitHub 写操作

用户明确说以下意图时，才执行对应 GitHub 写操作：

| 用户意图 | 动作 |
| --- | --- |
| `评论到 PR` / `发 review` / `发到 PR` | 发布对应 inline / conversation 评论。 |
| `Request Changes` / `请求修改` | 存在 P0 或阻塞合入问题时执行 request changes。 |
| `Approve` / `通过` | 先输出复查结论，再执行 approve，默认 approve body 为 `LGTM`。 |

授权模糊时必须先确认，不得猜测执行。

### b. Assignees

PR review 场景开始前必须补齐 assignees，未完成前不得继续 review 或执行 GitHub 写操作。

1. `gh api user --jq .login` 获取当前登录用户。
2. `gh pr view <pr> --json author --jq .author.login` 获取 PR 作者。
3. 去重后执行 `gh pr edit <pr> --add-assignee <login>`。
4. 执行 `gh pr view <pr> --json assignees --jq '.assignees[].login'` 校验。

失败时停止并告知用户，等待用户决策后再继续。

## 0x03 上下文收集

开始审查前，必须同时建立项目规范、变更内容和历史评论三类上下文。

| 上下文 | 要求 |
| --- | --- |
| 项目定位 | 目标项目已知时，先按工作区项目定位规则进入项目 `local_path`。 |
| 项目规范 | 优先读取目标仓库 `AGENTS.md`，再按项目类型读取 `pyproject.toml`、`package.json`、`go.mod`、lint / typecheck 配置等。 |
| 变更内容 | 查看 PR diff、本地 diff、相关源码、测试和配置变更。 |
| 历史评论 | 查看已有评论、未解决 review threads，以及用户要求复查的旧问题。 |
| 关联方案 | 用户以方案文档作为需求文档时，完整读取该 issue 目录的 `README.md`（需求）与 `PLAN.md`（方案）而非只读片段，据此建立需求基线、PR ↔ 里程碑映射与方案一致性基线。 |

不要只看 diff 片段就下结论。

## 0x04 审查重心

优先关注会影响合入安全的问题，再评估长期可维护性。

### a. 合入安全

| 重心 | 审查问题 |
| --- | --- |
| 向前兼容 | 未明确声明 breaking change 时，默认按非破坏性改动审查，重点检查既有调用方、配置、数据、API 和行为兼容性。 |
| 正确性 | 优先找会导致错误结果、异常、数据损坏、安全风险或发布回滚的问题。 |
| 测试覆盖 | 检查变更是否覆盖关键路径、兼容场景、失败路径和回归风险。 |
| 方案一致性 | review 关联方案时核对 PR 实现与方案约定的架构、协议、落点与边界是否一致：偏离若是实现缺陷按 P1 提出并指出对应方案条目，若是实现更优或方案已过期则记录差异并进入方案回写（见 [0x09 方案回写](#0x09-方案回写)）。 |

### b. 可维护性

| 重心 | 审查问题 |
| --- | --- |
| 命名与可读性 | 检查命名规范、代码格式、局部复杂度、注释必要性和项目风格一致性。 |
| 简洁实现 | 发现重复、绕路或过度复杂实现时，建议更简洁、可读的方案。 |
| 抽象设计 | 代码已出现扩展苗头时，评估是否需要合适的抽象或设计模式，不为假想扩展过早设计。 |

## 0x05 输出草稿

用户说 `review`、`复查`、`代码审查` 等时，先输出对话草稿报告。

报告固定包含：

1. `汇总评论`：整体结论、风险点、是否建议合入。
2. `新增问题`：本轮新发现的问题，按 P0 / P1 / P2 排序。
3. `已存在未解决 review 线程的解决情况`：用表格输出。

既有线程表格至少包含 `评论 / 线程`、`位置`、`状态`、`处理动作`、`证据`。

状态值固定为 `已修复`、`未修复`、`待确认`。

## 0x06 线程收口

用户触发 review 后，完成逐项核对的既有未解决 review thread 可以自动处理。

| 状态 | 动作 |
| --- | --- |
| `已修复` | 自动 resolve，并在报告中标注 `resolved`。 |
| `未修复` | 保持 unresolved，并说明仍缺少的修复。 |
| `待确认` | 不自动 resolve，说明争议点或证据缺口。 |

不对本轮新增评论自动 resolve。

用户明确要求不自动 resolve 时，遵循用户要求。

## 0x07 评论规范

### a. 严重程度

严重程度顺序固定为 P0 > P1 > P2。

| 级别 | 含义 |
| --- | --- |
| `P0` | 阻塞合入，存在明确正确性、安全、数据或发布风险。 |
| `P1` | 建议修复，风险较高或会造成维护成本。 |
| `P2` | 可选优化，不阻塞但能提升质量。 |

### b. 发布位置

可定位到文件与行号的问题，必须优先发布 inline review comment。

仅当问题无法定位到单行，或工具限制无法 inline 时，退化为 conversation 评论，并注明 `path:line` 与退化原因。

行内评论格式：

````markdown
**`path/to/file.go:42`** [P1]
> return nil

问题：错误返回值未处理，可能导致空指针。

建议：保留失败分支并返回原始错误：

~~~go
result, err := call()
if err != nil {
    return nil, err
}
~~~
````

评论内容结构：

- 必须包含明确问题、影响范围和修复方向。
- 默认使用「简洁文字 + 简洁核心伪代码」：文字说明风险、边界和修复目标，伪代码表达关键判断、数据流或调用结构；文字足够直接不能作为省略伪代码的理由。
- 只有极短 review 可以省略伪代码：问题与建议正文合计少于 `15` 个中文字符或 `15` 个英文单词，且只涉及变量命名、拼写、措辞、格式或同等规模的单点替换。
- 当对话中已经确认结构代码或关键实现形态时，PR 评论必须保留这些结构信号。
- 不要把已确认的结构方案压缩成泛化建议，导致作者无法直接落代码。
- 核心伪代码只提示关键变更：保留必要的判断、数据流和结构信号，省略样板代码与完整实现，不写成可直接套用的 diff。
- 非代码文件使用等价的最小结构示例：例如配置片段、协议字段或 Markdown 目标结构；与核心伪代码遵循同一省略门禁。
- 伪代码给开发者保留实现空间：只有影响正确性的边界细节必须明确写出。

极短 review 示例：

```markdown
**`path/to/file.py:42`** [P2]
> data = load_users()

Rename `data` to `users_by_id`.
```

Bad：

````markdown
[P1] 问题：错误来源应该做并集展示。这里发现已有 exception event 就直接返回，会让同一个 span 中已经上报的标准 exception event 和 attributes.rpc.error_code / attributes.trpc.status_code 变成互斥关系；后续 get_exception_events() 只会看到原始 events，无法再补充返回码逻辑异常，错误列表、详情和接口分布都会漏掉这类返回码错误。

建议：去掉这个早退，保留已有 events，并在存在 RPC/tRPC 错误码时额外 append 一个返回码 exception event。核心逻辑可以保持很简单：events = span.get(OtlpKey.EVENTS) or [] 后写回 span[OtlpKey.EVENTS] = events，然后沿用下面的返回码提取逻辑。这里 if code is None or code == "": 建议保留，并补一句注释说明不要写成 if not code，避免数值型错误码 0 被误判为空。
````

Good：

````markdown
[P1] 问题：错误来源应该做并集展示。当前已有 `exception` event 就直接 `return span`，会让已上报 events 和 RPC/tRPC 返回码逻辑异常变成互斥关系；同一个 span 同时包含两类错误来源时，返回码错误不会进入后续 `get_exception_events()`。

建议：去掉早退，保留已有 events，并在命中 RPC/tRPC 错误码时额外 append 返回码 `exception` event：

~~~python
events = span.get(OtlpKey.EVENTS) or []
span[OtlpKey.EVENTS] = events

for code_field, message_field in cls.RPC_EXCEPTION_FIELDS.items():
    code = (span.get(OtlpKey.ATTRIBUTES) or {}).get(code_field)
    # 不使用 `if not code`，避免数值型错误码 0 被误判为空。
    if code is None or code == "":
        continue

    events.append(build_rpc_exception_event(...))
~~~
````

### c. 评论语言

| 场景 | 语言 |
| --- | --- |
| 对话草稿 | 使用当前对话语言。 |
| 发布到 PR | conversation、inline review comment 和 approve body 使用目标项目 `language` 字段。 |
| 未配置语言 | 默认使用中文。 |

目标项目 `language` 字段从 `repos.json`、`private/repos.json` 读取。

## 0x08 交付自检

- 新增问题必须以风险为主，不把风格偏好伪装成阻塞问题。
- 每个 finding 都要有代码位置、影响说明和修复方向。
- 逐条检查 finding：除满足「少于 `15` 个中文字符或英文单词」的极短 review 外，每条评论都必须同时包含简洁文字和简洁核心伪代码。
- 核心伪代码必须保持提示粒度，不得膨胀为完整实现或 diff。
- 没有发现问题时，明确说明未发现阻塞问题，并列出残余风险或未覆盖检查。
- 发布到 PR 的评论必须和用户最终确认的草稿完全一致。
- 发布前逐条比对最终草稿，禁止在发布时二次改写、压缩、补充或删减。
- 发布到 PR 前再次确认 inline 评论、总结评论和语言选择。
- 关联方案的 review，必须完成方案回写核对：版本锚点是否登记本次 PR / 分支 / 状态，以及实现与方案是否存在实质出入，缺口在草稿中给出同步或询问动作。

## 0x09 方案回写

review 是方案与现实对齐的关键契机，关联方案时按 knowledge-mgr 技能的方案写作与回写规范落实结论。

本 skill 只在此阶段触发核对、产出差异，不锚定其具体规则，规范遗忘时召回 knowledge-mgr 补读。

| 回写场景 | 触发 | review 侧产物 |
| --- | --- | --- |
| 版本锚点 | PR / 分支 / 状态与方案登记的锚点不一致。 | 用 `gh pr view` 取真值，草稿输出「版本锚点核对」（当前值 / 实际值 / 动作）。 |
| 方案与实现对齐 | 实现更优、边界调整、协议变化或方案过期。 | 草稿单列「方案差异」（方案原述 / 实际实现 / 性质 / 建议），主动询问是否回写方案。 |

约束：

- 缺陷类偏离按 [0x04 审查重心](#0x04-审查重心) 走 P1，不回写方案。
- 不擅自重写方案：先在草稿给出核对 / 差异与拟改要点，经用户确认或明确指令后再回写。
- 回写按 knowledge-mgr 的方案规范执行，GitHub 写操作仍遵循 [0x02 权限门禁](#0x02-权限门禁)。