rust-code-review

Rust 代码审查

审查是对一项变更应履行义务的说明——既要回应提出变更的请求，也要遵守仓库一贯遵循的标准。本技能将这两项分别审查，再合并成一份以结论为先的报告。它不会复述某种代码异味所对应的规则：编码规范由相关技能和 /rust-testing 负责，审查则会指向它们。

分开审查两个方面

同一位审查者同时检查代码是否符合请求和编码质量，往往两方面都做不好：规格偏差会被表面整洁的代码掩盖，而风格上的小问题又会盖过遗漏的边界情况。应分别进行标准审查和规格审查，然后合并；若运行环境支持，则使用并行子 Agent，否则依次进行。两项审查的提示词、合并规则和报告格式见 REVIEW-PASSES.md。

先让机器检查

在任一审查开始阅读代码之前，先执行下面的验证步骤并查看输出。clippy 已经报告的问题不属于审查发现；那是有人忘了运行的构建检查。审查者应关注工具无法发现的问题：需要判断的情况、遗漏的边界情况，以及悄然扩大的范围。

判断风格前，先阅读仓库的 lint 配置

检查 Cargo.toml 中的 [lints.clippy]、clippy.toml、rustfmt.toml，以及 crate 根目录中的 #![deny(...)]。若某项发现与仓库有意设置的级别相矛盾，那就不是发现，而是一项提议，应明确说明。绝不要使用比仓库配置更严格的级别重新运行检查，再把额外报告的问题当作缺陷。代码异味基准是在此配置之上叠加，而不是取而代之——如果仓库的 lint 配置已经允许某种情况，那么相关发现针对的就是配置，应另行提出。

代码异味基准

本技能在 clippy 之外还会检查 lint 无法判断的问题。完整表格列出了代码异味、它在差异中的表现、为何属于缺陷，以及负责处理它的技能，见 SMELLS.md。主要问题包括：

• 调用处出现无法解释的 clone — /ownership-not-clone
• 在调用者可控制的执行路径上使用 unwrap 或 expect — /rust-errors
• 某项没有外部调用方却被标记为 pub — /rust-api-design
• 本应使用枚举的布尔型或字符串类型参数 — /type-driven-design
• 在异步函数中执行阻塞操作 — /async-rust
• unsafe 代码块没有 // SAFETY: 注释 — /unsafe-rust
• 行为发生变化，却没有能捕获该变化的测试 — /rust-testing

失去原有理由的 #[allow(lint)] 会一直存在，却无人察觉。情况发生变化后，#[expect(lint, reason = "...")] 会检查失败；这样一来，被屏蔽的 lint 过时后便会自行报告。在审查中，没有理由的 #[allow] 属于问题；有理由的则可以讨论。

严重程度，以及何时不写

仅分三个级别：阻塞（行为错误、存在不健全之处，或未提升版本号便破坏公共 API）、应修复（作者确实需要了解的缺陷）、备注（真实存在但作者可以选择不采纳的改进）。低于此门槛的问题应直接舍弃，而非记录下来——一份列出四十个小问题和一个健全性缺陷的审查，会让那个缺陷被淹没。不要用赞美凑字数，也不要把差异内容复述给作者。

问题格式

每项一行，按严重程度从高到低排列：路径:行号 — 严重程度：问题所在。应如何处理。

src/cache.rs:41 — blocking: guard held across .await; drop it before the fetch.
src/parse.rs:8 — should-fix: unwrap on caller input; return the ParseError instead.
src/lib.rs:102 — note: this fn takes String where &str would do.

如果某项问题没有具体的修复方案，那它就是一个问题，应以疑问句表述。

本技能不负责的事项

它不会重写代码——只提出问题，不提供补丁，除非作者提出要求。它不会审查无法构建的差异：无法运行的检查应在报告中明确指出，而不是掩盖过去。它不会决定移植项目的兼容性约定；这属于 /port-to-rust。

验证

报告前运行，并在报告中引用结果：

cargo fmt --check
cargo clippy --all-targets --all-features   # at the repo configured level; add -- -D warnings only if there is no lint config
cargo test --all-features

如果其中任何一项无法运行——例如依赖项无法联网获取，或必需组件没有 nightly 版本——报告应指出未运行的检查，而不是暗示所有检查均已通过。