professional-rust-review（professional Rust 审查）

Professional Rust Review

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.

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

References

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.

Step 1: Identify the Target

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).

Step 2: Delegate the crew

Delegate using teams with anthropic/claude-opus-4-6.

Step 2a.: Delegate the Surgeon

The worker must:

1. Read references/professional-rust.md completely first
2. Read the target code broadly before diving deep
3. Find specific locations where applying a principle materially changes the code
4. Show BEFORE and AFTER code for each finding
5. 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'."

Step 2b.: Delegate the Zen Master

The worker must:

1. Read references/codebase-organization.md completely first
2. Read the target code broadly before diving deep (not just filenames)
3. Find specific locations where applying a principle materially improves the architecture
4. Show BEFORE and AFTER for each finding
5. 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'."

Step 3: Formulate the Dispatch

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'
  }
])

Template A: Surgeon

Fill in {placeholders}:

# Deep Rust Code Surgery

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

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

## 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:

1. Show the EXACT current code (file path, line range, the actual code)
2. Explain what principle applies and WHY it matters HERE (not in general)
3. Show the REWRITTEN code — the actual diff
4. 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.

## Output
Write to {output_path}. Structure each finding as:

# Surgery N: [descriptive title]
**File:** path:line_range
**Principle:** §N — [name]
**Why here:** [specific reasoning for THIS code]

### Before

[actual current code]

### After

[rewritten code]

**What this prevents:** [specific scaling problem avoided]

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

Template B: Zen Master

Fill in {placeholders}:

# Rust Codebase Structural Review

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.

## Target

{description of crates/workspace to review, with paths} {workspace layout if multi-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:

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

## 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.

## Output

Write to {output_path}. Structure each finding as:

# Finding N: [descriptive title]

**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.

Step 4: Present Results

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.

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

The 47 principles span 10 areas:

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.