review-rust

Rust 代码审查

参数

• --parallel：如果 Agent 支持子 Agent，则针对每个技术领域并行分派一个；否则按顺序执行，输出保持一致。
• 路径：目标目录（默认为当前工作目录）

硬性门槛

在输出中撰写 问题 前，按顺序完成以下步骤（范围为空也可以；不得捏造发现）。

1. **范围门槛：**明确列出正在审查的 .rs 路径（来自步骤 1 或用户提供的路径）。**通过条件：**打印路径列表或写明“范围内没有 Rust 文件”——然后停止，不输出问题。
2. **编译器／代码检查工具门槛：**从 crate 或工作区根目录（存在 Cargo.toml）运行步骤 3 中的命令；如果无法运行，需用一行说明原因（例如，缺少工具链、没有 Cargo.toml、沙盒限制）。**通过条件：**不得报告步骤 3 输出中已显示为错误／警告的问题，也不得重复报告作者必须先修复的编译器或 clippy 诊断。
3. **协议门槛：**在步骤 7 前加载 review-verification-protocol 技能。**通过条件：**每项严重／主要发现均符合步骤 8（以及该协议）的要求；如果没有发现，在审查摘要中写明“已应用协议；没有问题”。
4. **证据门槛（严重／主要）：**对于每项严重或主要问题，需结合完整上下文重新阅读 FILE:LINE 处的文件（不能只看差异代码块）。**通过条件：**问题描述与该位置可观察到的代码一致。

步骤 1：确定变更文件

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.rs$'

步骤 2：检查 Rust Edition 和 MSRV

# Check Cargo.toml for edition and rust-version
grep -E 'edition|rust-version' Cargo.toml

# Check workspace members if workspace
grep -A 20 '\[workspace\]' Cargo.toml

Edition 2024 注意事项（要求 MSRV 1.85+）：

如果检测到 edition = "2024"，则整个审查过程中都适用以下行为变更：

• unsafe_op_in_unsafe_fn 默认设为 deny——unsafe fn 中的 unsafe 操作必须使用显式的 unsafe {} 代码块
• extern "C" {} 代码块必须写为 unsafe extern "C" {}
• #[no_mangle] 和 #[export_name] 必须写为 #[unsafe(no_mangle)] 和 #[unsafe(export_name)]
• -> impl Trait 默认捕获所有作用域内的生命周期（RPIT 生命周期捕获变更）；使用 + use<'a> 进行精确捕获
• gen 是保留关键字——将其用作标识符的代码必须改用 r#gen
• !（never 类型）会回退为 !，而不是 ()——这可能改变推断类型的行为
• if let 条件和尾部表达式中的临时值会比 Edition 2021 中更早释放
• Box<[T]> 现在实现了 IntoIterator

记录检测到的 edition——这会影响步骤 3、步骤 8 和验证协议中的严重性评估。

步骤 3：验证代码检查工具状态

关键：在指出风格或正确性问题之前，先运行 clippy 和 check。不要指出 clippy 或编译器已能发现的问题。

cargo clippy --all-targets --all-features -- -D warnings 2>&1 | head -50
cargo clippy -- -D clippy::perf 2>&1 | head -20
cargo check --all-targets 2>&1 | head -50

**Edition 2024 注意事项：**Edition 2024 将若干此前仅产生警告的 lint 提升为 deny（尤其是 unsafe_op_in_unsafe_fn）。如果 clippy 或 cargo check 已报告与 edition 相关的错误，不要将其重复列为审查发现；应改为说明作者必须先修复编译器错误。

步骤 4：检测技术

# Detect tokio async runtime
grep -r "tokio" --include="Cargo.toml" -l | head -3

# Detect axum web framework
grep -r "axum" --include="Cargo.toml" -l | head -3

# Detect sqlx database
grep -r "sqlx" --include="Cargo.toml" -l | head -3

# Detect serde serialization
grep -r "serde" --include="Cargo.toml" -l | head -3

# Detect thiserror / anyhow
grep -r "thiserror\|anyhow" --include="Cargo.toml" -l | head -3

# Detect tracing
grep -r "tracing" --include="Cargo.toml" -l | head -3

# Check for test files in diff
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '((^|/)(test|tests)/.*\.rs$)|(_test\.rs$)'

# Check for unsafe code in diff
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -c 'unsafe'

# Detect async fn in traits (no async-trait crate needed since Rust 1.75)
grep -r "async-trait" --include="Cargo.toml" -l | head -3

# Detect LazyLock/LazyCell usage (replaces once_cell/lazy_static since 1.80)
grep -r "once_cell\|lazy_static" --include="Cargo.toml" -l | head -3

# Detect #[expect] lint attribute usage (stable since 1.81)
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -c '#\[expect('

# Detect macro definitions in diff
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'macro_rules!|#\[proc_macro|#\[derive\('

# Detect FFI code in diff
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'extern "C"|#\[no_mangle\]|#\[repr\(C\)\]|bindgen|#\[unsafe\(no_mangle\)\]'

# Detect concurrency primitives (atomics, lock-free, hand-rolled sync)
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'std::sync::atomic|Atomic(Bool|U?size|U?(8|16|32|64)|Ptr)|compare_exchange|fetch_(add|sub|or|and|xor|update)|UnsafeCell|unsafe impl (Send|Sync)|Ordering::(Relaxed|Acquire|Release|AcqRel|SeqCst)|atomic::fence'

# Detect concurrency test tooling
grep -rE 'loom|^miri$' --include='Cargo.toml' -l | head -3
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'loom::|#\[cfg\(loom\)\]|cfg_attr\(miri'

# Detect concurrency crates
grep -rE '^crossbeam|^arc-swap|^parking_lot|^dashmap|^flurry|^haphazard|^seize|^atomic_wait' --include='Cargo.toml' -l | head -3

# Detect criterion benchmarks
grep -rE '^criterion' --include='Cargo.toml' -l | head -3
ls -d benches 2>/dev/null

# Detect proc-macro crate or trybuild
grep -rE 'proc-macro\s*=\s*true|^trybuild' --include='Cargo.toml' -l | head -3

# Detect public-surface changes (interface-design.md routing)
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE '^\+\s*pub (trait|fn|struct|enum|mod|use)|^\+\s*impl[<\s].*Drop for'

# Detect ecosystem patterns (patterns-in-the-wild.md routing)
grep -rE '^slotmap|^petgraph|^scopeguard|^indexmap' --include='Cargo.toml' -l | head -3
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'mem::replace|swap_remove|prelude'

现代 Rust 检测说明：

• 如果 async-trait 是依赖项，但项目使用 edition 2024 或 MSRV >= 1.75，则标记为提示信息 — trait 中原生支持 async fn，很可能可以移除 async-trait。
• 如果 once_cell 或 lazy_static 是依赖项，但 MSRV >= 1.80，则标记为提示信息 — std::sync::LazyLock 和 std::cell::LazyCell 是稳定的替代方案。
• 如果在适合使用 #[expect(...)] 而非 #[allow(...)] 的情况下使用了 #[allow(...)]（MSRV >= 1.81），则标记为轻微问题 — 当被抑制的 lint 不再触发时，#[expect] 会发出警告，从而保持抑制项整洁。

并发检测说明：

• 如果差异中出现原子操作（std::sync::atomic、compare_exchange、fetch_*）、UnsafeCell、unsafe impl Send/Sync 或 crossbeam / arc-swap / parking_lot，则加载 rust-code-review 技能，并参考其中的 references/concurrency-primitives.md、references/memory-ordering.md 和 references/lock-free-patterns.md。
• 如果差异引入或重构了并发机制（工作线程池、actor 风格的通道、tokio::spawn 模式、线程与异步的取舍），还应参考 references/concurrency-models.md 中的设计层面审查问题。
• 如果出现手写原子操作 / 无锁类型，但没有 loom 依赖或 CI 中没有 cargo +nightly miri test，则加载 rust-testing-code-review 技能，并参考其中的 references/concurrency-testing.md。

接口设计 / API 表面检测：

• 如果差异引入或更改了 pub trait、pub fn、pub struct、公共类型上的派生实现、拥有资源的类型上的 impl Drop，或外部类型的重新导出，则加载 rust-code-review 技能，并参考其中的 references/interface-design.md，检查对象安全性、实现的易用性、可能失败的析构函数以及隐藏契约。
• 如果差异使用了索引指针图（Vec<Node> + usize、slotmap、petgraph）、mem::replace 风格的 drop guard、扩展 trait，或修改了 prelude 模块，还应参考 references/patterns-in-the-wild.md。

测试检测（criterion / trybuild / clippy 策略）：

• 如果存在 benches/ 目录或 criterion 依赖，则加载 rust-testing-code-review 技能，并参考其中的 references/advanced-testing.md，检查 criterion 基线、black_box 和 iter_batched。
• 如果存在过程宏 crate（proc-macro = true）或 [dev-dependencies] 中包含 trybuild，则参考 rust-testing-code-review 技能的 references/advanced-testing.md，检查 trybuild .stderr 稳定性；同时参考 macros-code-review 技能的 references/procedural-macros.md，检查 span 卫生和 syn 特性审计。

步骤 5：加载验证协议

加载 review-verification-protocol 技能，并在整个审查过程中牢记其中的检查清单。

第 6 步：加载技能

阅读各项适用技能的 SKILL.md 并应用其中的要求（例如，加载 rust-code-review 技能）。

始终加载：

• rust-code-review

根据检测结果有条件地加载：

条件	技能
检测到 Tokio	tokio-async-code-review
检测到 Axum	axum-code-review
检测到 sqlx	sqlx-code-review
检测到 Serde	serde-code-review
更改了测试文件	rust-testing-code-review
diff 中包含宏定义	macros-code-review
检测到 FFI 代码（extern、repr(C)、bindgen）	ffi-code-review
原子操作、UnsafeCell、unsafe impl Send/Sync、compare_exchange、crossbeam、arc-swap、parking_lot	rust-code-review（加载 references/concurrency-primitives.md、references/memory-ordering.md、references/lock-free-patterns.md）
并发设计变更（工作线程池、通道、线程与异步之间的结构调整）	rust-code-review（加载 references/concurrency-models.md）
公共 trait / pub fn / pub struct / impl Drop / 重新导出变更	rust-code-review（加载 references/interface-design.md）
图/树代码、slotmap、petgraph、mem::replace 丢弃守卫、扩展 trait、prelude 模块变更	rust-code-review（加载 references/patterns-in-the-wild.md）
criterion 基准测试、benches/ 目录	rust-testing-code-review（加载 references/advanced-testing.md — 检查 criterion 基线、black_box 和 iter_batched）
过程宏 crate（proc-macro = true）或 dev-deps 中包含 trybuild	rust-testing-code-review + macros-code-review（加载 references/advanced-testing.md 中的 trybuild 内容 + references/procedural-macros.md 中的 span hygiene 内容）
测试中使用 loom、miri、手写的无锁代码	rust-testing-code-review（加载 references/concurrency-testing.md）

第 7 步：审查

如果 Agent 支持子 Agent，则按技术领域并行分派任务；否则，在单个上下文中按顺序审查。两种方式的输出相同。

并行方式（Agent 支持子 Agent）：

1. 提前检测所有技术
2. 按技术领域分派一个子 Agent
3. 每个子 Agent 加载相应技能并审查其领域
4. 等待所有子 Agent 完成
5. 汇总审查结果

顺序方式（不支持子 Agent）：

1. 加载适用技能
2. 审查 Rust 核心质量（所有权、错误处理、unsafe、trait）
3. 依次审查每个检测到的技术领域
4. 汇总审查结果

第 8 步：验证发现

报告任何问题之前：

1. 重新阅读实际代码（而不只是差异上下文）
2. 对于“未使用”的说法——你是否搜索了整个工作区中的所有引用？
3. 对于“缺失”的说法——你是否检查了 trait 定义、派生宏和受 #[cfg] 控制的代码？
4. 对于“不必要的克隆”——你是否确认借用检查器允许使用引用？
5. 对于“不安全”问题——你是否检查了安全注释和周围的不变量？
6. 删除任何属于风格偏好而非实际问题的发现

Edition 2024 验证规则： 7. 不要将 unsafe fn 内部的 unsafe {} 块标记为不必要——在 Edition 2024 中这是必需的 8. 不要将 unsafe extern "C" 标记为不常见语法——在 Edition 2024 中这是必需的 9. 不要将 #[unsafe(no_mangle)] 或 #[unsafe(export_name)] 标记为不常见——在 Edition 2024 中这是必需的 10. 对于返回 -> impl Trait 的情况，请确认隐式生命周期捕获是否有意为之——在 Edition 2024 中，默认会捕获所有作用域内的生命周期；只有需要更窄的捕获范围时，才建议使用 + use<'a> 11. 对于在迭代器上下文中使用 Box<[T]> 的代码，请记住 Edition 2024 现已支持 IntoIterator——不要将 .iter() 标记为访问装箱切片的唯一方式 12. 如果 if let 或尾部表达式中的临时值导致借用问题，请考虑这是否由 Edition 2024 更早的析构语义引起

第 9 步：审查收敛

单轮审查的完整性

你必须在单轮审查中报告所有类别（所有权、错误处理、异步、类型、测试、安全、性能）中的所有问题。不要把问题留到后续轮次。

提交发现之前，先问自己：

• “如果应用了我建议的所有修复，我是否会在修复后的代码中发现新问题？”
• “我是否要求编写新代码（测试、类型、模块），而这些代码本身也需要审查？”

如果其中任一项的答案是“是”，请在本轮审查中立即包含这些预期的后续问题，以便作者一次性处理完毕。

范围规则

• 仅审查差异中的代码及其直接相关的现有代码
• 不要要求添加差异之前不存在的新功能、测试基础设施或架构变更
• 如果缺少测试覆盖，将其作为一个次要问题标记（“缺少对 X、Y、Z 的测试覆盖”）——不要指定实现细节
• 文档注释、命名问题均为次要问题，除非它们影响公共 API 契约
• 不要要求添加新依赖（例如 proptest、mockall、criterion）

修复复杂度预算

无论修复规模如何，都应按其实际严重程度标记现有代码中的修复。

但是，对于差异之前不存在的新代码的请求，必须归类为信息性：

• 添加新依赖
• 创建全新的模块、文件或测试套件
• 提取新的 trait 或抽象
• 添加基准测试套件

这些是供作者在后续工作中考虑的改进建议，不是审查阻塞项。

迭代策略

如果这是修复后的复审：

• 只验证之前标记的问题是否得到正确解决
• 不要提出与之前审查问题无关的新发现
• 接受未修复的次要/可选问题——不要再次标记
• 复审的目标是验证，而不是发现问题

输出格式

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (unsound unsafe, data race, panic, security)
   - Fix: Specific recommended fix

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

规则

• 撰写问题之前，先完成硬性门槛
• 审查之前加载技能（而不是审查之后）
• 为每个问题按顺序编号（1、2、3……）
• 为每个问题注明文件和行号
• 清晰区分问题、原因和修复方法
• 按实际严重程度分类
• 标记风格问题之前运行 clippy
• 修复后运行验证
• 在单轮审查中报告所有问题——不要把发现留到后续轮次
• 复审仅验证之前的修复——不进行新的问题发现
• 对新增代码（新模块、依赖、测试套件）的请求属于信息性，不构成阻塞
• 评估结论忽略次要和信息性项目——只有严重和主要问题会阻止批准

修复后验证

应用修复后，运行：

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

所有检查都必须通过后才能批准。