professional-rust-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Professional Rust Review

专业Rust代码评审

Deep code surgery using a field guide extracted from ripgrep (46K LOC), clap (41K LOC), parsel (6K LOC), and ring_api (2.3K LOC). Not design patterns. The actual craft — line-by-line decisions that separate code that rots from code that lives.

基于从ripgrep（4.6万行代码）、clap（4.1万行代码）、parsel（6千行代码）和ring_api（2.3千行代码）中提炼的实战指南，进行深度代码优化。这不是设计模式，而是真正的编码工艺——逐行的决策区分了易腐化的代码和可长期维护的代码。

When to Use

适用场景

Reviewing Rust code for quality (any crate, any size)
Writing new Rust types, traits, or modules and want professional patterns
Auditing a crate for scaling problems before they compound
Reviewing or designing crate/module organization and structure
User says "review", "judge", "audit", "improve" about Rust code

评审任意 crate、任意规模的Rust代码质量
编写新的Rust类型、trait或模块时，想要遵循专业模式
在问题恶化前审计crate的可扩展性问题
评审或设计crate/模块的组织架构
用户要求对Rust代码进行「评审」「评判」「审计」「改进」

References

参考资料

File	Contents	When to load
`references/professional-rust.md`	47 principles on types, signatures, traits, errors, modules, macros, config, testing, performance, discipline	Dispatching a code surgery worker — the worker reads it as rubric
`references/codebase-organization.md`	Module layout, facade pattern, privacy ladder, dependency direction, `std_ext` mirroring, unsafe auditing, encapsulation progression	Dispatching a structural review worker — the worker reads it as rubric

文件路径	内容	加载时机
`references/professional-rust.md`	关于类型、签名、trait、错误、模块、宏、配置、测试、性能、编码规范的47条原则，附带原理和失效模式说明	分派代码优化工作者时——工作者将其作为评审准则
`references/codebase-organization.md`	模块布局、外观模式、可见性层级、依赖方向、 `std_ext` 镜像、unsafe代码审计、封装演进等相关原则	分派结构评审工作者时——工作者将其作为评审准则

How It Works

工作流程

Two review modes. Pick based on what the user asks for, or run both.

Code surgery — line-level craft quality. Uses
```
references/professional-rust.md
```
.
Structural review — module layout, privacy design, dependency flow. Uses
```
references/codebase-organization.md
```
.

Delegate an opus-level worker with the relevant guide as rubric. Do NOT summarize the guide in the prompt — the worker reads it directly.

提供两种评审模式，可根据用户需求选择其一，或同时运行两种模式。

代码优化 —— 逐行级别的编码工艺质量检查，使用
```
references/professional-rust.md
```
作为准则。
结构评审 —— 模块布局、可见性设计、依赖流向检查，使用
```
references/codebase-organization.md
```
作为准则。

分派资深工作者，并以相关指南作为评审准则。请勿在提示词中总结指南内容——工作者将直接阅读指南原文。

Step 1: Identify the Target

步骤1：确定评审目标

Determine which Rust files or crates to review. Use

fd -e rs

and

wc -l

to scope the work. Exclude auto-generated files (bindings, protobuf output).

明确需要评审的Rust文件或crate。使用

fd -e rs

和

wc -l

确定评审范围。排除自动生成的文件（如绑定代码、protobuf输出文件）。

Step 2: Delegate the crew

步骤2：分派工作者

Delegate using

teams

with

anthropic/claude-opus-4-6

使用

teams

工具，指定模型为

anthropic/claude-opus-4-6

进行分派。

Step 2a.: Delegate the Surgeon

步骤2a：分派代码优化专家

The worker must:

Read
```
references/professional-rust.md
```
completely first
Read the target code broadly before diving deep
Find specific locations where applying a principle materially changes the code
Show BEFORE and AFTER code for each finding
Explain why the change matters HERE, not in general

Critical instruction quality rules:

"Find ALL specific locations" — not "check all 47 principles"
"Show the exact current code and the exact rewritten code" — not "this pattern is missing"
"Explain what breaks as the codebase grows without this change" — not "best practice says X"
"Do NOT produce a checklist. Do NOT say '❌ Missing'."

工作者必须：

先完整阅读
```
references/professional-rust.md
```
先整体浏览目标代码，再深入细节
找出所有应用准则后会实质性改变代码的具体位置
为每个问题点提供「优化前」和「优化后」的代码
解释为什么此处需要修改（而非泛泛而谈）

关键规则：

「找出所有具体位置」——而非「检查全部47条原则」
「展示当前代码和修改后的完整代码」——而非「此处缺少某模式」
「解释若不修改，代码库扩展时会出现什么问题」——而非「最佳实践要求X」
「请勿生成检查清单，请勿使用'❌ 缺失'这类表述」

Step 2b.: Delegate the Zen Master

步骤2b：分派架构评审专家

The worker must:

Read
```
references/codebase-organization.md
```
completely first
Read the target code broadly before diving deep (not just filenames)
Find specific locations where applying a principle materially improves the architecture
Show BEFORE and AFTER for each finding
Explain why the change matters HERE, not in general

Critical instruction quality rules:

"Find ALL specific locations" — not "check all principles"
"Show the current state VS acceptable end state
"Explain what breaks as the codebase grows without this change" — not "best practice says X"
"Do NOT produce a checklist. Do NOT say '❌ Missing'."

工作者必须：

先完整阅读
```
references/codebase-organization.md
```
先整体浏览目标代码（而非仅文件名），再深入细节
找出所有应用准则后会实质性改进架构的具体位置
为每个问题点提供「当前状态」和「优化后状态」
解释为什么此处需要修改（而非泛泛而谈）

关键规则：

「找出所有具体位置」——而非「检查全部原则」
「展示当前状态与理想状态的对比」
「解释若不修改，代码库扩展时会出现什么问题」——而非「最佳实践要求X」
「请勿生成检查清单，请勿使用'❌ 缺失'这类表述」

Step 3: Formulate the Dispatch

步骤3：构建分派指令

Dispatch both workers in parallel using a single

teams

call:

teams(action: 'delegate', tasks: [
  {
    text: '<surgeon request — see template A below>',
    assignee: 'rust-surgeon',
    model: 'anthropic/claude-opus-4-6'
  },
  {
    text: '<zen-master request — see template B below>',
    assignee: 'rust-zen-master',
    model: 'anthropic/claude-opus-4-6'
  }
])

通过单次

teams

调用，并行分派两位工作者：

teams(action: 'delegate', tasks: [
  {
    text: '<代码优化专家请求——见下方模板A>',
    assignee: 'rust-surgeon',
    model: 'anthropic/claude-opus-4-6'
  },
  {
    text: '<架构评审专家请求——见下方模板B>',
    assignee: 'rust-zen-master',
    model: 'anthropic/claude-opus-4-6'
  }
])

Template A: Surgeon

模板A：代码优化专家

Fill in

{placeholders}

undefined

填充

{placeholders}

占位符：

undefined

Deep Rust Code Surgery

Rust代码深度优化

Read the professional Rust field guide at {skill_dir}/references/professional-rust.md completely first. It contains 47 principles with reasoning and failure modes.

请先完整阅读位于{skill_dir}/references/professional-rust.md的专业Rust实战指南，其中包含47条附带原理和失效模式的编码原则。

Target

评审目标

{description of crates/files to review, with paths} {any files to EXCLUDE like auto-generated bindings}

{需要评审的crate/文件描述及路径} {需要排除的文件，如自动生成的绑定代码}

Rules

规则

Do NOT produce a checklist. Do NOT say '❌ Missing'.
Do NOT list principles that don't apply.
Every finding must include BEFORE code and AFTER code from the actual codebase.
The AFTER code must compile (or be obviously close). No pseudocode.
Focus on changes that affect SCALABILITY — what makes adding the next feature harder or easier.

请勿生成检查清单，请勿使用'❌ 缺失'这类表述。
请勿列出不适用的原则。
每个问题点必须包含来自实际代码库的「优化前」和「优化后」代码。
优化后的代码必须可编译（或明显接近可编译状态），请勿使用伪代码。
聚焦于影响可扩展性的修改——即哪些修改会影响新增下一个功能的难易程度。

What to Find

检查要点

Find ALL locations where applying a principle would materially change the code. For each:

Show the EXACT current code (file path, line range, the actual code)
Explain what principle applies and WHY it matters HERE (not in general)
Show the REWRITTEN code — the actual diff
Explain what breaks or degrades without the change as the codebase grows

找出所有应用原则后会实质性改变代码的位置。针对每个问题点：

展示精确的当前代码（文件路径、行号范围、代码内容）
说明适用的原则，以及为什么此处需要应用该原则（而非泛泛而谈）
展示修改后的代码——即实际的代码差异
解释若不修改，代码库扩展时会出现什么问题

What to Look For

检查方向

Don't grep for keywords. READ the code and find:

A function that takes
```
String
```
where
```
&str
```
or
```
impl Into<>
```
would prevent unnecessary allocation
An enum matched on externally when methods on the enum would centralize logic
A struct with
```
pub
```
fields mutated from 3 modules when encapsulation would help
A
```
HashMap<u64, X>
```
where a newtype key would prevent mixing up ID types
A
```
Result<(), String>
```
that forces callers to parse strings to understand failures
A function returning
```
Option<T>
```
without
```
#[must_use]
```
where callers forget to check
A hot loop calling a cross-crate function without
```
#[inline]
```
A type constructed once and never mutated with
```
String
```
fields that should be
```
Box<str>
```
An
```
.unwrap()
```
that will panic in production under specific conditions
A 200+ line function that should be 5 methods on a struct

Read broadly first. Then dive deep.

请勿通过关键词搜索，需通读代码并找出以下问题：

函数参数使用
```
String
```
，但使用
```
&str
```
或
```
impl Into<>
```
可避免不必要的内存分配
外部代码直接匹配enum，而将逻辑集中在enum的方法中会更合理
struct的
```
pub
```
字段被3个不同模块修改，而封装机制可提升代码可维护性
使用
```
HashMap<u64, X>
```
，但使用新类型作为键可避免ID类型混淆
使用
```
Result<(), String>
```
，导致调用者必须解析字符串才能理解错误原因
函数返回
```
Option<T>
```
但未添加
```
#[must_use]
```
，导致调用者可能忘记检查返回值
热点循环中调用跨crate函数，但未添加
```
#[inline]
```
注解
类型仅初始化一次且后续不会修改，但字段使用
```
String
```
而非
```
Box<str>
```
```
.unwrap()
```
会在生产环境特定条件下触发panic
函数长度超过200行，可拆分为struct的5个方法

先整体浏览代码，再深入细节。

Output

输出格式

Write to {output_path}. Structure each finding as:

将结果写入{output_path}。每个问题点按以下结构展示：

Surgery N: [descriptive title]

优化点N：[描述性标题]

File: path:line_range Principle: §N — [name] Why here: [specific reasoning for THIS code]

文件： 路径:行号范围 适用原则： §N — [原则名称] 此处修改原因： [针对当前代码的具体理由]

Before

优化前

rust

[actual current code]

rust

[实际当前代码]

After

优化后

rust

[rewritten code]

What this prevents: [specific scaling problem avoided]

Order by impact (most impactful first). Do NOT create tickets.

undefined

rust

[修改后的代码]

优化效果： [避免的具体可扩展性问题]

按影响程度排序（影响最大的在前）。请勿创建工单。

undefined

Template B: Zen Master

模板B：架构评审专家

Fill in

{placeholders}

undefined

填充

{placeholders}

占位符：

undefined

Rust Codebase Structural Review

Rust代码库结构评审

Read the codebase organization guide at {skill_dir}/references/codebase-organization.md completely first. It contains principles for module layout, privacy, dependency direction, and encapsulation with concrete patterns.

请先完整阅读位于{skill_dir}/references/codebase-organization.md的代码库组织指南，其中包含模块布局、可见性、依赖方向和封装的相关原则及具体模式。

Target

评审目标

{description of crates/workspace to review, with paths} {workspace layout if multi-crate}

{需要评审的crate/工作区描述及路径} {多crate工作区的布局说明}

Rules

规则

Do NOT produce a checklist. Do NOT say '❌ Missing'.
Do NOT list principles that don't apply.
Every finding must reference specific files, modules, and dependency paths.
Proposed restructuring must be concrete — show the directory tree or module moves.
Focus on what makes the NEXT feature harder to add or the next developer slower to onboard.

请勿生成检查清单，请勿使用'❌ 缺失'这类表述。
请勿列出不适用的原则。
每个问题点必须关联具体的文件、模块和依赖路径。
提出的重构方案必须具体——展示目录树或模块移动方案。
聚焦于影响新增功能难度和新开发者上手速度的问题。

What to Find

检查要点

Find ALL structural problems in this codebase. For each:

Show the CURRENT structure (module tree, file paths, pub/use chains)
Explain what organizational principle applies and WHY it matters HERE
Show the PROPOSED structure — the actual module moves, visibility changes, or re-exports
Explain what breaks or degrades without the change as the codebase grows

找出代码库中所有结构问题。针对每个问题点：

展示当前结构（模块树、文件路径、pub/use引用链）
说明适用的组织原则，以及为什么此处需要应用该原则
展示建议的结构——即实际的模块移动、可见性修改或重新导出方案
解释若不修改，代码库扩展时会出现什么问题

What to Look For

检查方向

Map the codebase first. THEN find:

Modules organized by technical role (models/, utils/, helpers/) instead of by feature
A module re-exporting everything with
```
pub use
```
— no facade, just a pass-through
Cross-module dependency loops (A uses B, B uses A)
```
pub
```
fields on structs where
```
pub(crate)
```
or private + methods would enforce invariants
A
```
utils.rs
```
or
```
helpers.rs
```
grab-bag that should be
```
std_ext/
```
mirroring std
Tooling (benchmarks, fuzz targets, CLI tools) living inside the main crate instead of workspace members
A deeply nested module path that should be facaded at a higher level
Private items that are
```
pub
```
for no reason — check who actually imports them
An
```
unsafe
```
block without a safety comment or justification
A struct with a reset/clear/serialize method that doesn't destructure (risks missing new fields)

Read the full module tree first. Then dive deep.

先梳理代码库结构，再找出以下问题：

模块按技术角色（models/、utils/、helpers/）而非功能组织
模块通过
```
pub use
```
导出所有内容——没有外观层，仅作为中转
跨模块依赖循环（A依赖B，B依赖A）
struct的字段使用
```
pub
```
，但使用
```
pub(crate)
```
或私有字段+方法可保证不变性
```
utils.rs
```
或
```
helpers.rs
```
作为万能工具包，应重构为
```
std_ext/
```
镜像标准库结构
工具代码（基准测试、模糊测试、CLI工具）位于主crate内，应作为工作区独立成员
模块路径嵌套过深，应在更高层级提供外观层
无理由设为
```
pub
```
的私有项——检查实际的引用方
```
unsafe
```
代码块未添加安全注释或理由说明
struct的reset/clear/serialize方法未使用解构，可能遗漏新增字段

先通读完整的模块树，再深入细节。

Output

输出格式

Write to {output_path}. Structure each finding as:

将结果写入{output_path}。每个问题点按以下结构展示：

Finding N: [descriptive title]

问题点N：[描述性标题]

Location: module path / file paths involved Principle: [name from the guide] Why here: [specific reasoning for THIS codebase]

位置： 涉及的模块路径/文件路径 适用原则： [指南中的原则名称] 此处修改原因： [针对当前代码库的具体理由]

Current Structure

当前结构

[actual module tree, dependency arrows, or visibility chain]

[实际的模块树、依赖箭头或可见性链]

Proposed Structure

建议结构

[concrete restructuring — directory moves, visibility changes, new modules]

What this prevents: [specific scaling or maintainability problem avoided]

Order by impact (most impactful first). Do NOT create tickets.

undefined

[具体的重构方案——目录移动、可见性修改、新增模块等]

优化效果： [避免的具体可扩展性或可维护性问题]

按影响程度排序（影响最大的在前）。请勿创建工单。

undefined

Step 4: Present Results

步骤4：呈现结果

When both workers return, synthesize findings from both into a single report. Summarize the top 5 findings from each worker in a table, then point to the full reports.

If the user wants to act on findings, create tickets for the top-priority items using

tk

两位工作者完成任务后，将两者的发现整合成一份报告。在表格中汇总每位工作者的前5个关键发现，然后指向完整报告。

如果用户希望跟进这些发现，使用

tk

工具为优先级最高的问题创建工单。

What the Guides Cover (for reference, do not load into worker prompt)

指南覆盖范围（仅供参考，无需加载到工作者提示词中）

The 47 principles span 10 areas:

Part	Principles	Area
I	§1–§7	Types: newtypes, enums vs bools, hidden inner enums, right-sized types, Box<str>, Cow, bytes vs strings
II	§8–§13	Signatures: Into vs AsRef, ?Sized, monomorphization firewall, &mut Self vs self, #[must_use]
III	§14–§19	Traits: minimum surface, iteration style, generics vs trait objects, closure adapters, associated types
IV	§20–§25	Errors: custom vs anyhow, user vs programmer, structured context, mechanical context, bool callbacks
V	§26–§29	Modules: pub(crate), deny(missing_docs), facade crates, types-carry-behavior
VI	§30–§32	Macros: boilerplate only, field-type bounds, dummy impls
VII	§33–§35	Config: private config/public builder/frozen product, two-phase processing, cost-tiered dispatch
VIII	§36–§39	Testing: Result-returning tests, roundtrip testing, behavior not structure, colocated tests
IX	§40–§42	Performance: #[inline], FlatMap, no unnecessary async
X	§43–§47	Discipline: lint config, #[non_exhaustive], documenting omissions, owning critical path, FromStr before serde

47条原则分为10个领域：

部分	原则编号	领域
I	§1–§7	类型：新类型、enum与bool对比、隐藏内部enum、合适大小的类型、Box<str>、Cow、字节与字符串
II	§8–§13	签名：Into与AsRef对比、?Sized、单态化防火墙、&mut Self与self对比、#[must_use]
III	§14–§19	Trait：最小接口、迭代风格、泛型与trait对象对比、闭包适配器、关联类型
IV	§20–§25	错误：自定义错误与anyhow对比、用户错误与开发者错误对比、结构化上下文、机械上下文、bool回调
V	§26–§29	模块：pub(crate)、deny(missing_docs)、外观crate、类型承载行为
VI	§30–§32	宏：仅用于消除样板代码、字段类型约束、空实现
VII	§33–§35	配置：私有配置/公共构建器/冻结产物、两阶段处理、成本分层分派
VIII	§36–§39	测试：返回Result的测试、往返测试、行为测试而非结构测试、测试代码与生产代码同目录
IX	§40–§42	性能：#[inline]、FlatMap、避免不必要的async
X	§43–§47	编码规范：lint配置、#[non_exhaustive]、文档说明遗漏内容、控制关键路径、优先实现FromStr而非serde

Common Mistakes

常见错误

Checklist mode: The worker produces a table of "present/absent" for each principle. Useless. The instructions explicitly forbid this — if the worker falls into checklist mode, the dispatch prompt needs sharpening.

Theoretical findings: "You could use Cow here." Without showing the current code, the rewrite, and why it matters for THIS codebase, it's noise.

Too many findings, too shallow: 15 deep findings beat 47 shallow ones. The worker should read broadly, then pick the 15 highest-impact sites and go deep on each.

Ignoring auto-generated code: Always exclude bindings, protobuf output, and other generated files from review scope.

undefined

检查清单模式： 工作者生成每个原则的「存在/缺失」表格，这毫无用处。指令中明确禁止这种模式——如果工作者陷入这种模式，需要优化分派提示词。

理论化发现： 比如「此处可以使用Cow」，但未展示当前代码、修改后的代码，以及为什么当前代码库需要这个修改，这属于无效信息。

发现过多但深度不足： 15个深度发现远胜于47个浅层发现。工作者应先整体浏览代码，然后挑选15个影响最大的点进行深度分析。

忽略自动生成代码： 评审范围必须排除绑定代码、protobuf输出等自动生成的文件。

undefined