Code Review Five Axis Zh

---
name: code-review-five-axis-zh
description: 五轴代码评审（正确性/可读性/架构/安全/性能）、变更大小控制、评审意见分级、依赖变更评审、评审速度与分歧处理。当用户说「帮我评审这个 PR」「合并前把把关」「这个 PR 太大了怎么拆」「评审意见怎么分必须改和建议」「升级依赖的 PR 怎么审」「评审里意见不一致怎么办」时使用。要点：批准标准是"确定改善整体健康"而非完美；五轴各自的检查问题；结构性问题要给出具名的修法；~100 行好、~300 可接受、~1000 要拆，四种拆法；变更描述首行祈使独立成句；流程先看意图再看测试再看实现；意见前缀（无前缀=必须、Critical、Nit、Optional、FYI），先说最重要的；多模型评审；死代码先问再删；一个工作日内响应；分歧按事实>规范>设计原则>一致性；每次一个依赖、读变更日志、看锁文件 diff。也覆盖「五个维度给意见」「怎么拆」「该怎么审」这类说法。改编自 addyosmani/agent-skills 的 code-review-and-quality（MIT）。
author: Captain
version: 0.1.1
display_name: "五轴代码评审"
display_name_en: "Five-Axis Code Review (zh)"
description_zh: "正确性、可读性、架构、安全、性能五轴评审；变更大小与拆法、意见分级前缀、先看意图和测试、结构性问题给具名修法、依赖升级逐个评审、分歧按事实优先。"
description_en: "Review on correctness, readability, architecture, security and performance; size changes and split them, label findings by severity, read intent and tests first, propose named structural remedies, review dependency bumps one at a time, resolve disputes by facts first."
tags:
  - "代码评审"
  - "code review"
  - "五轴评审"
  - "PR 评审"
  - "依赖升级"
  - "评审分级"
examples_zh:
  - "评审这个 PR，按五个维度给意见并标出必须改的"
  - "这个 PR 改了 1200 行，怎么拆"
  - "一个升级 20 个依赖的 PR 该怎么审"
examples_en:
  - "Review this PR on five axes and mark what must change"
  - "This PR touches 1200 lines, how should it be split"
  - "How do I review a PR that bumps 20 dependencies"
metadata:
  { "openclaw": { "requires": { "bins": ["git"] }, "os": ["darwin", "linux", "windows"], "emoji": "🧭" } }
---

# 五轴代码评审

## 何时用
每个改动合并前都评审，无例外——PR 打开时用它按五轴走一遍；PR 太大无法评审、评审意见需要分级、或依赖升级 PR 需要单独审时尤其适用。不替代自动化检查（lint/类型/测试），是人工评审这一步的纪律。

每个改动合并前都评审，无例外。**批准标准**：只要它**确定改善了代码库整体健康**就批准，哪怕不完美；不因为"不是我会写的样子"而卡。（与本系列「代码评审（双轴）」互补：那个分"标准 vs Spec"两轴并有预扫脚本；这个给五个维度的检查问题与评审流程纪律。）

## 五轴
1. **正确性**：符合规格吗；边界（空、空集、边界值）；错误路径；测试是否真的在测对的东西；off-by-one、竞态、状态不一致。
2. **可读性与简单**：名字清楚且合项目约定；控制流直白；组织合理；有没有该化简的"聪明"；**能更短吗**；抽象值回复杂度吗（第三个用例前别泛化）；注释是否说明了非显然意图；有没有死代码残留；**新条件是不是硬塞进了无关流程**（设计味道，不是小问题——应该进它自己的 helper/状态/策略）；**同一形状的条件反复出现**（缺模型或分发器，"临时"分支通常永久）。
3. **架构**：遵循现有模式还是引入新模式（新模式有理由吗）；模块边界；重复；依赖方向（无环）；抽象层级适当；**重构是减少复杂度还是搬运复杂度**——数读者要记住的概念数，没减就不算更干净，优先让整条分支/模式/层消失的重构；**功能逻辑是否泄漏进共享模块**；**类型边界是否显式**（质疑随手的 any/unknown/可选/断言和掩盖不清不变量的静默兜底）。
4. **安全**（细则见「安全加固」）：输入校验；密钥不入代码/日志/版本库；该查的鉴权都查了；参数化查询；输出编码；依赖可信无已知漏洞；外部来源数据当不可信并在边界校验。
5. **性能**（细则见「性能优化」）：N+1；无界循环或抓取；该异步的同步；不必要重渲染；列表无分页；热路径建大对象。

## 结构性修法要具名
只说"太复杂"让作者猜。给出动作：把条件链换成类型化模型或显式分发器；折叠重复分支；把编排与业务逻辑分开；把功能逻辑从共享模块搬回拥有它的包；复用规范 helper 而不是近似复制；把类型边界显式化让下游分支消失；删掉只加间接层的透传包装；抽 helper 或拆大文件。优先移除活动部件的修法。

## 变更大小
~100 行好（一次能审完）；~300 单一逻辑变更可接受；~1000 太大要拆。**也看文件大小**：小 diff 也能把文件推过 ~1000 行的健康边界——先拆再加。"一个变更" = 处理一件事、含相关测试、提交后系统仍可工作。拆法：叠（先提小的，下一改基于它）/ 按文件组（不同评审者）/ 水平（先共享代码与桩，再消费者）/ 垂直（更小的全栈切片）。可接受的大变更：整文件删除、只需确认意图的自动化重构。**重构与功能分开提交。**
变更描述：首行短、祈使、独立成句（"删除 FizzBuzz RPC"），搜历史的人不看 diff 也能懂；正文写改了什么、为什么、代码里看不出的决策与取舍，链接工单/基准/设计文档。反例："修 bug""修构建""阶段 1""加便捷函数"。

## 流程
1. **先懂意图**：要完成什么、实现哪份规格、预期行为变化。2. **先看测试**：存在吗、测行为不测实现、覆盖边界、命名描述性、改坏了能抓到吗。3. **再看实现**：逐文件过五轴。4. **给意见分级**：无前缀 = 必须改；**Critical** = 阻塞合并（安全、丢数据、功能坏）；**Nit** = 可忽略的风格；**Optional/Consider** = 建议；**FYI** = 仅供参考。**先说最重要的**：按杠杆排序——正确性与安全 → 结构回退与错过的化简 → 其他；一个结构问题加十个 nit，结构问题才是评审。5. **核实验证故事**：跑了什么测试、构建、手测、UI 截图、前后对比。

## 多模型评审
A 写代码 → B 审正确性与架构 → A 处理意见 → 人拍板。不同模型盲点不同。评审提示："按正确性、安全、项目约定评审；规格说 X，改动应 Y；按 Critical / Required / Optional / Nit 标记。"

## 死代码卫生
重构后找出不可达/未用的代码，列出来，**先问再删**："这些已无引用，可以删吗：…"。别留着，也别悄悄删不确定的。

## 评审速度
慢评审阻塞整个团队；切换成本小于让别人等的成本。最迟一个工作日内响应（上限不是目标）；理想是收到请求后很快回，除非深度专注中；先快速逐条反馈，而不是憋一个最终批准；大变更让作者拆而不是硬审。

## 分歧
事实与数据 > 意见；风格指南是风格问题的绝对权威；设计按工程原则而非个人偏好；与代码库一致可接受，只要不损害整体健康。**不接受"以后再清理"**——推迟的清理很少发生；除非真紧急，要求提交前清理，或至少建 issue 自己认领。

## 评审里的诚实
不橡皮图章（没有证据的 LGTM 帮不了任何人）；不软化真问题；能量化就量化（"这个 N+1 每条加 ~50ms"）；对明显有问题的方案直接反对并给替代；作者有完整上下文且坚持时优雅接受；评代码不评人。

## 依赖纪律
**加依赖前**：现有栈能解决吗；多大；还在维护吗；已知漏洞；许可证兼容。优先标准库与现有工具，每个依赖都是负债。
**升级依赖**是普通代码变更，最危险的是"bump deps"式一揽子合并：读变更日志不只看版本号（semver 是维护者可能没守住的承诺）；**一次一个依赖**（一揽子挂了不知道是谁，单包改动原因清楚回退干净）；由测试裁决（前后都绿，不是"装上了"；覆盖薄就是真正的发现，先补测试）；看传递图（审锁文件 diff 不只 package.json）；锁文件诚实（提交、审 diff、不手改）。审计与供应链风险的裁决见「安全加固」。

## 评审清单（摘要）
上下文：懂它做什么为什么。正确性：符合规格、边界、错误路径、测试充分。可读性：名字、逻辑直白、无多余复杂度。架构：现有模式、无多余耦合、抽象适当、重构真减复杂度、无功能逻辑进共享模块、文件大小健康。安全：无密钥、边界校验、无注入、鉴权、外部数据不可信。性能：无 N+1、无无界操作、列表分页。验证：测试过、构建过、必要时手测。结论：批准 / 要求修改。

## 合理化借口对照

| 借口 | 现实 |
|---|---|
| "能用就够了" | 难读、不安全、架构错的能用代码是复利的债 |
| "我写的我知道对" | 作者对自己的假设是盲的 |
| "以后再清理" | 以后不会来；评审就是质量门 |
| "AI 写的大概没问题" | AI 代码需要更多审视：自信且貌似合理，哪怕错了 |
| "测试过了就行" | 测试必要不充分：抓不到架构、安全、可读性 |
| "重构让它更干净了" | 搬运复杂度不是减少；读者要记的概念没少就没改善 |
| "只是给这个文件加一点" | 小 diff 也能把文件推过健康边界、把分支塞进无关流程 |
| "只是升个版本" | 版本变更是你没写的行为变更；读变更日志 |
| "一个 PR 全升了省事" | 一揽子挂了藏住了是谁；一次一个原因与回退都干净 |

## 红灯
不评审就合并；只看测试过没过；无证据的 LGTM；安全敏感改动没有安全视角评审；太大没法审的 PR；修 bug 的 PR 没回归测试；意见没有级别；接受"以后修"；只搬代码不减概念数的重构；把大文件推得更大而不拆；新条件散进无关路径；近似复制现有 helper 或功能逻辑进共享模块；无变更日志评审、不按包隔离的一揽子升级；手改/未提交/未审 diff 的锁文件。

## 验收
```
- [ ] Critical 全部解决　- [ ] Required 全部解决或有理由明确推迟　- [ ] 测试通过　- [ ] 构建成功　- [ ] 验证故事已记录　- [ ] 依赖升级按包隔离、看过变更日志、测试前后绿、审过锁文件 diff
```
**推定阻塞**（先给更简单的设计，只有结构变得更糟时升级为必须改）：搬运复杂度的重构；把文件推过大小边界而不拆；功能逻辑进共享模块；近似复制规范 helper；掩盖不清不变量的静默兜底。

---
改编自 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) 的 `code-review-and-quality`（MIT）。改动见 ATTRIBUTION.md。