让AI代理像资深工程师一样审查Rust代码：BeautifulRust三级报告与规则引用完整解析

想让 AI 代理审查 Rust 代码并得到一份"像资深工程师一样较真"的报告？BeautifulRust 项目的 rust-review 技能正是为此而生：它教 Claude Code、Codex、Cursor、Gemini CLI 等编码代理按统一的审查清单检查 Rust 代码，输出一份三级优先级报告（Must fix / Should fix / Consider），每条问题都标注 file:line 位置、可查证的规则出处，并附上最小化修复代码。

为什么 AI 审查 Rust 代码需要"较真"的规范 🧐

直接问 AI"帮我看看这段 Rust 代码"，常见结果是：

• 问题一锅端，不区分"会崩溃的 bug"和"风格瑕疵"
• 只说"这里写得不好"，说不出违反了哪条规则
• 给出大段重写代码，而不是精准的最小修复
• 只挑毛病，不告诉你哪些地方已经写得很好

rust-review 技能把资深工程师的审查习惯固化成了 skills/rust-review/SKILL.md 里的一套流程：先定范围 → 跑工具 → 按优先级找问题 → 写结构化报告。它的输出是一份审查报告，而不是重写代码——改不改、怎么改，决定权在作者手里。

审查流程：先跑工具，再找设计问题 🔧

技能定义了五个步骤，其中值得新手了解的是前两步：

1. 确定范围：只审查你指的东西（一个文件、一个模块、一个 crate 或一份 diff），并在报告开头说明按"库"还是"应用"标准来审——库代码会被严格套用 API 设计规范，应用代码则侧重简洁。
2. 先跑工具：在 crate 根目录执行 cargo fmt --check、cargo clippy -- -W clippy::pedantic、cargo test，把机械性问题交给工具，把"脑力"留给设计层面。报告里会如实说明工具是否运行过。

这一步很关键：clippy 能抓到的 unwrap()、缺文档问题会被归并进对应发现，而不是把原始输出糊你一脸。

三级报告结构：Must fix / Should fix / Consider 📋

报告的核心结构在 SKILL.md 的"Write the report"一节中定义，分三个层级：

级别	含义	典型例子
Must fix	会出事的：bug、soundness 漏洞、可达的 panic、发布后无法收回的 API 失误	unwrap() 读外部输入文件
Should fix	能用但违反规则且有真实代价	错误信息缺失、&String 参数、HashMap 顺序泄漏
Consider	风格、命名与打磨	bool 参数、缺少 Debug 派生

排序规则很硬：真正会崩的东西永远排在风格建议前面。一个短文件 5～10 条发现就够了，禁止凑数，也不许把真 bug 淹没在风格细节里。

每条发现三件套：位置 + 规则出处 + 修复代码 ✅

rust-review 对每条发现有三条铁律，也是它"较真"的来源：

• 引用位置：写成 inventory.rs:76 这样的 file:line；找不到单一位置（如"整个文件没测试"）则标注 whole file
• 引用规则：给出可查证的规则名和出处，如 Rust API Guidelines 的 C-GOOD-ERR、Effective Rust Item 18、Microsoft 指南的 M-PANIC-ON-BUG、clippy lint 名 unwrap_used——读者都能自己翻到原文
• 修复写成代码：只展示"改动的那几行"，不重写整个函数；重复问题合并成一条（"8 处 unwrap()"列出行号，而不是 8 条发现）

报告最后还有强制的 "What's already good" 一节，列出 2～4 条代码已经做对的事——这既告诉作者哪些要保留，也让整份报告更可信。

实战示例：一份真实的审查报告 📖

项目内置了一份技能生成的真实报告：examples/review-inventory.md，审查对象是故意写得"坑坑洼洼"的库存模块 skills/rust-review/evals/review-inventory-module/files/inventory.rs。看看报告如何定位最高优先级问题：

发现 1（Must fix）：加载文件时遇到坏输入直接 panic

模块的 load 和 parse_line 明明返回了 Result，但内部对文件不存在（read_to_string(path).unwrap()）或非数字数量（parse::<i64>().unwrap()）一律崩溃——数据文件里一个手误就能拖垮整个调用方。

规则：Don't panic on expected failures（Effective Rust Item 18；M-PANIC-ON-BUG，Microsoft Rust Guidelines）；clippy：unwrap_used、missing_panics_doc

修复（报告给出的最小改动）：

let text = std::fs::read_to_string(path)
    .map_err(InventoryError::Io)?;
let qty: i64 = parts[1].trim().parse()
    .map_err(|e| InventoryError::Parse { field: "qty", source: e })?;

发现 2（Must fix）：错误类型对调用者毫无用处

InventoryError 没有实现 Display 和 std::error::Error，变体也不携带任何数据——NotFound 不说找不见的是哪个商品，Parse 不说错在第几行哪个字段。报告给出的修复是用 thiserror 重写错误枚举，每个变体带上下文并标注 #[non_exhaustive]。

发现 11（Consider）：bool 参数语义模糊

report(verbose: bool) 里那个 true 到底代表什么？报告建议换成枚举：

pub enum ReportDetail { Summary, Verbose }

这份报告的完整面貌——包括 Rc<RefCell<Inventory>> 出现在公开 API、&String 参数应改为 &str、#![deny(warnings)] 会让 clippy 直接报错等 13 条发现——都可以直接在 examples/review-inventory.md 里对照阅读。

💡 注意：报告全程不修改源码。示例报告明确声明 "inventory.rs itself was not modified"，审查与建议分离，是这份技能的基本立场。

报告质量如何被验证：12 项评测断言 🧪

rust-review 的评测案例 skills/rust-review/evals/review-inventory-module/case.yaml 要求代理只写 REVIEW.md、不许改代码，graders/ 目录下 12 个文件每项一条断言，例如：

• 01-flags-panics-as-top-priority.md：panic 类问题必须排进最高优先级
• 08-findings-cite-locations.md：每条发现都要引用行号
• 09-findings-cite-named-rules.md：至少三分之二的发现要引用可查证的规则名
• 11-says-what-is-good.md：必须说清代码哪里做得好
• 12-code-left-unchanged.md：源码必须保持原样

README.md 记录了实测成绩：启用该技能后代理通过 11/12 项断言，不启用只有 7/12。

安装与触发：一句话开始审查 🚀

每个技能都是 skills/ 下的一个文件夹，三种常见安装方式：

# 通用安装器（支持大多数代理）
npx skills add morganlinton/BeautifulRust

# Claude Code 插件方式
claude plugin install beautiful-rust --marketplace morganlinton/BeautifulRust

# 手动复制到共享技能目录
mkdir -p ~/.agents/skills
cp -R skills/rust-* ~/.agents/skills/

安装后无需手动调用，直接对代理说"review src/parser.rs"或"这个 PR 有什么可以改的"，rust-review 就会自动触发。建议三个技能一起装：审查技能依赖 skills/rust-best-practices/ 的规则库来查证拿不准的条款，references/ 里收录了 Google Rust Style Guide、Rust API Guidelines、Effective Rust 等五份权威资料的精读摘要。

搭配 clippy 配置：让规则在 CI 里持续生效 ⚙️

审查报告会主动建议接入项目的 lint 配置：lints/lints.toml 是一份即贴即用的 <a href="https://link.gitcode.com/i/5d455d841f053370ca5a6eee91b9c651" target="_blank">lints] 块，[lints/clippy.toml 提供阈值设置。它覆盖的正是报告里的高频问题：

• unwrap_used / panic_in_result_fn：禁止用 panic 处理预期失败
• missing_errors_doc / missing_panics_doc：公开函数必须写 # Errors、# Panics
• fn_params_excessive_bools：拒绝语义模糊的 bool 参数
• undocumented_unsafe_blocks：每个 unsafe 块都要 // SAFETY: 注释

cargo clippy --all-targets --all-features -- -D warnings

项目还配了一个"证据链"：lints/check/ 是一个故意违规的测试 crate，scripts/check-lints.sh 在 CI 里跑 clippy，证明表格里每条 lint 真的会触发，任何一条静默失效都会让构建失败。AI 审查管设计，clippy 管机械问题，两者正好是同一套规则的一体两面。

总结：把"较真"沉淀成可复用的规范 📌

回顾一下 rust-review 的四个要点：

1. 三级报告：Must fix / Should fix / Consider，真 bug 永远压过风格建议
2. 规则引用：每条发现给出 file:line 位置和可查证的规则出处
3. 修复代码：只写改动的那几行，重复问题合并，不整段重写
4. 保持平衡：强制列出代码已经做对的地方，且绝不擅自修改源码

配合可验证的评测与 CI lint 体系（CHANGELOG.md 记录了持续演进），它给新手团队的启示很直接：AI 审查的价值不在于"会说"，而在于把资深工程师的审查纪律变成一份可验证、可复用的标准流程。