Claude Skill

rust-best-practices

Write, review, or refactor Rust so it is idiomatic, safe, and maintainable. Use this skill whenever the task involves Rust code — implementing a feature in a `.rs` file, reviewing a Rust PR or module, refactoring a crate, designing a public API, fixing clippy or borrow-checker co

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download adulari-forge-crates_forge-skills_builtin_rust-best-practices-c191129.zip · 4 KB

Install

skills CLI npx skills add https://github.com/adulari/forge/tree/main/crates/forge-skills/builtin/rust-best-practices
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install adulari-forge@llmmart
Git git clone https://github.com/adulari/forge.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole adulari/forge collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Rust Best Practices

Idiomatic Rust is not a style preference — it is how you get the compiler and the ecosystem to catch your mistakes for you. The goal of every guideline here is to move a class of bug from "found in production" to "found at compile time" or "found by cargo clippy". When you apply a rule, understand which failure it prevents; that lets you know when the rule genuinely doesn't apply.

Before you write code

Read the surrounding module first. A crate has a texture — its error type, its naming, how it splits modules, whether it leans on iterators or explicit loops. Match it. A locally "more correct" pattern that fights the existing conventions is worse than a consistent one, because the next reader now has to hold two mental models.

The verification gate (non-negotiable)

Rust code is not done until these pass. Run them and fix what they report — do not report success on unverified code.

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

cargo fmt removes all whitespace and layout debate. clippy with -D warnings is the single highest-leverage habit in Rust: it catches needless clones, non-idiomatic patterns, likely bugs, and performance traps before review. If a lint is genuinely wrong for a case, #[allow(clippy::x)] it locally with a one-line reason — never blanket-allow at crate level, which silences future real hits.

Error handling

This is where most non-idiomatic Rust shows up. The rules:

  • Return Result, propagate with ?. Don't match a Result just to re-return it. ? is the idiom; it also converts error types through From, which is the whole point.
  • unwrap / expect / panic! are for "this cannot fail and if it does the program is broken". In library code and any path driven by external input, they are bugs waiting to happen. expect("reason") beats unwrap() because the message documents the invariant and shows up in the panic. Reserve bare unwrap() for tests and truly impossible cases.
  • Applications vs libraries pick different error crates:
    • Application / binary: anyhow::Result<T> with .context("what failed") at each boundary. You want a readable error chain, not a typed taxonomy the caller matches on.
    • Library: a typed error enum via thiserror, so callers can match on variants and your error is std::error::Error. Libraries should not force anyhow on their users.
  • Errors are meaningful and well-behaved (Rust API Guideline C-GOOD-ERR): implement Debug, Display, and Error; carry enough context to act on; never stringify away structure the caller needs.
  • Don't swallow errors with let _ = or .ok() unless ignoring them is genuinely correct — and if it is, a short comment says why.

Ownership, borrowing, and types

  • Borrow, don't clone, to satisfy the borrow checker. A .clone() added only to make an error go away is a smell — usually the fix is &, a lifetime, or restructuring. Clone when you genuinely need an owned copy, not as a borrow-checker escape hatch.
  • Accept the most general type; return the most specific. Take &str not &String, &[T] not &Vec<T>, impl AsRef<Path> not &PathBuf. Return concrete types the caller can use directly.
  • Make illegal states unrepresentable. Encode invariants in the type system: a newtype (struct UserId(u64)) instead of a bare u64; an enum instead of a bool + Option combo that has meaningless states. Arguments should convey meaning through types, not positional bools (API Guideline C-CUSTOM-TYPE).
  • Prefer iterators and combinators (map, filter, collect, ?-in-iterator via collect::<Result<_,_>>()) over manual index loops — they are clearer and eliminate off-by-one and bounds bugs. Don't force it, though: a plain for loop with side effects is fine when a combinator chain would be more obscure.
  • Derive the common traits (Debug, Clone, PartialEq, and Eq/Hash/Default/ Copy where they make sense). Every public type should implement Debug (C-DEBUG).

API design (public interfaces)

  • Follow the naming conventions: as_/to_/into_ for conversions by cost, iter/ iter_mut/into_iter for iterators, RFC 430 casing.
  • Keep struct fields private and expose behavior through methods, so you can change internals without a breaking release (C-STRUCT-PRIVATE).
  • Use the builder pattern for types with many optional fields rather than a telescoping constructor or a giant Option-filled new.
  • Implement standard conversion traits (From, TryFrom, AsRef) instead of ad-hoc to_x/from_x free functions; From gives you Into for free and plugs into ?.
  • Document every public item with a rustdoc comment, and include a # Errors section for fallible functions and a # Panics section for ones that can panic. Examples in docs are compiled and tested — they double as regression tests.

Size and structure

These are conventions, not compiler limits — but they track real maintainability, and clippy enforces the function one by default.

Scope Practical target Basis
Function / method ≤ 100 lines clippy too_many_lines default threshold is 100.
.rs file / module ≤ ~1,000 lines No compiler/clippy limit; a common team convention. Split by responsibility.
Crate No line cap Split around a real API / domain / dependency boundary, not a line count.
Published .crate ≤ 10 MB compressed crates.io hard limit on the packaged archive.

Exceptions that legitimately blow past the file target: generated code, large lookup tables/fixtures, and macro-heavy modules. When a function crosses ~100 lines, the fix is almost always to extract a well-named helper, not to #[allow] the lint — the name you give the extracted piece is documentation.

Organize modules by responsibility, not by type-kind (mod users beats a mod structs). Keep the crate's public surface in lib.rs/mod.rs re-exports so callers have one obvious import path.

Unsafe

  • Default to safe Rust. Reach for unsafe only for FFI, genuine performance-critical spots proven by measurement, or building a safe abstraction over a raw operation.
  • Every unsafe block gets a // SAFETY: comment stating the invariant that makes it sound. Keep unsafe blocks minimal and wrapped in a safe API so the unsafety doesn't leak.

Dependencies

  • Add a dependency when it earns its keep; each one is compile time, audit surface, and a future upgrade. Prefer well-maintained, widely-used crates.
  • Use precise-enough version requirements, keep Cargo.lock committed for binaries, and run cargo update deliberately. Consider cargo deny / cargo audit for license and vulnerability checks on anything shipped.
  • Fill in Cargo.toml metadata for published crates (description, license, repository, keywords, categories) — C-METADATA.

Testing

  • Unit tests live in a #[cfg(test)] mod tests beside the code; integration tests go in tests/. Test behavior and edge cases, not just the happy path.
  • Prefer table-driven tests for multiple input/output cases. Use assert_eq! with meaningful values so failures are legible.
  • Doctests keep examples honest — put a runnable example on public functions.
  • For parsing/serialization and anything with an input space, consider property tests (proptest/quickcheck).

Async (when it applies)

  • Don't block in async code (std::fs, std::thread::sleep, long CPU loops) — it stalls the executor. Use the async equivalents or spawn_blocking.
  • Don't hold a std::sync::Mutex guard across an .await. Use an async-aware lock or drop the guard first.
  • Don't add async to a function that never awaits.

Applying this in a review

When reviewing Rust rather than writing it, scan in this order — it surfaces the highest-value issues first: (1) unwrap/expect/panic! on fallible or input-driven paths; (2) error handling that discards context or matches-to-re-return instead of ?; (3) needless clones and overly-specific parameter types; (4) missing Debug/derives on public types and missing docs on public items; (5) oversized functions that should be split; (6) any unsafe without a // SAFETY: justification. Point to path:line, say which failure the issue invites, and prefer suggesting the idiomatic shape over just naming the rule.

Files (forge)
  • SKILL.md 9.4 KB
    ---
    name: rust-best-practices
    description: >-
      Write, review, or refactor Rust so it is idiomatic, safe, and maintainable. Use this
      skill whenever the task involves Rust code — implementing a feature in a `.rs` file,
      reviewing a Rust PR or module, refactoring a crate, designing a public API, fixing
      clippy or borrow-checker complaints, deciding how to structure error handling, or
      splitting an oversized function or file. Trigger even when the user does not say
      "best practices" explicitly: any request to "write this in Rust", "clean up this Rust
      code", "is this idiomatic", "add a Cargo crate", "handle these errors properly", or
      "make this compile without unwrap" should pull in this skill. Covers ownership and
      borrowing, error handling (Result / `?` / thiserror / anyhow), API design, module and
      crate layout, size limits, unsafe, dependencies, testing, and the verification steps
      (fmt, clippy, test) that must pass before the work is called done.
    tier: standard
    ---
    
    # Rust Best Practices
    
    Idiomatic Rust is not a style preference — it is how you get the compiler and the
    ecosystem to catch your mistakes for you. The goal of every guideline here is to move a
    class of bug from "found in production" to "found at compile time" or "found by
    `cargo clippy`". When you apply a rule, understand which failure it prevents; that lets
    you know when the rule genuinely doesn't apply.
    
    ## Before you write code
    
    Read the surrounding module first. A crate has a texture — its error type, its naming, how
    it splits modules, whether it leans on iterators or explicit loops. Match it. A locally
    "more correct" pattern that fights the existing conventions is worse than a consistent one,
    because the next reader now has to hold two mental models.
    
    ## The verification gate (non-negotiable)
    
    Rust code is not done until these pass. Run them and fix what they report — do not report
    success on unverified code.
    
    ```
    cargo fmt --all
    cargo clippy --all-targets --all-features -- -D warnings
    cargo test
    ```
    
    `cargo fmt` removes all whitespace and layout debate. `clippy` with `-D warnings` is the
    single highest-leverage habit in Rust: it catches needless clones, non-idiomatic patterns,
    likely bugs, and performance traps before review. If a lint is genuinely wrong for a case,
    `#[allow(clippy::x)]` it *locally* with a one-line reason — never blanket-allow at crate
    level, which silences future real hits.
    
    ## Error handling
    
    This is where most non-idiomatic Rust shows up. The rules:
    
    - **Return `Result`, propagate with `?`.** Don't `match` a `Result` just to re-return it.
      `?` is the idiom; it also converts error types through `From`, which is the whole point.
    - **`unwrap` / `expect` / `panic!` are for "this cannot fail and if it does the program is
      broken".** In library code and any path driven by external input, they are bugs waiting
      to happen. `expect("reason")` beats `unwrap()` because the message documents the invariant
      and shows up in the panic. Reserve bare `unwrap()` for tests and truly impossible cases.
    - **Applications vs libraries pick different error crates:**
      - *Application / binary*: `anyhow::Result<T>` with `.context("what failed")` at each
        boundary. You want a readable error chain, not a typed taxonomy the caller matches on.
      - *Library*: a typed error enum via `thiserror`, so callers can match on variants and your
        error is `std::error::Error`. Libraries should not force `anyhow` on their users.
    - **Errors are meaningful and well-behaved** (Rust API Guideline C-GOOD-ERR): implement
      `Debug`, `Display`, and `Error`; carry enough context to act on; never stringify away
      structure the caller needs.
    - Don't swallow errors with `let _ =` or `.ok()` unless ignoring them is genuinely correct —
      and if it is, a short comment says why.
    
    ## Ownership, borrowing, and types
    
    - **Borrow, don't clone, to satisfy the borrow checker.** A `.clone()` added only to make an
      error go away is a smell — usually the fix is `&`, a lifetime, or restructuring. Clone when
      you genuinely need an owned copy, not as a borrow-checker escape hatch.
    - **Accept the most general type; return the most specific.** Take `&str` not `&String`,
      `&[T]` not `&Vec<T>`, `impl AsRef<Path>` not `&PathBuf`. Return concrete types the caller
      can use directly.
    - **Make illegal states unrepresentable.** Encode invariants in the type system: a newtype
      (`struct UserId(u64)`) instead of a bare `u64`; an `enum` instead of a `bool` + `Option`
      combo that has meaningless states. Arguments should convey meaning through types, not
      positional `bool`s (API Guideline C-CUSTOM-TYPE).
    - **Prefer iterators and combinators** (`map`, `filter`, `collect`, `?`-in-iterator via
      `collect::<Result<_,_>>()`) over manual index loops — they are clearer and eliminate
      off-by-one and bounds bugs. Don't force it, though: a plain `for` loop with side effects is
      fine when a combinator chain would be more obscure.
    - **Derive the common traits** (`Debug`, `Clone`, `PartialEq`, and `Eq`/`Hash`/`Default`/
      `Copy` where they make sense). Every public type should implement `Debug` (C-DEBUG).
    
    ## API design (public interfaces)
    
    - Follow the naming conventions: `as_`/`to_`/`into_` for conversions by cost, `iter`/
      `iter_mut`/`into_iter` for iterators, RFC 430 casing.
    - Keep struct fields private and expose behavior through methods, so you can change internals
      without a breaking release (C-STRUCT-PRIVATE).
    - Use the **builder pattern** for types with many optional fields rather than a telescoping
      constructor or a giant `Option`-filled `new`.
    - Implement standard conversion traits (`From`, `TryFrom`, `AsRef`) instead of ad-hoc
      `to_x`/`from_x` free functions; `From` gives you `Into` for free and plugs into `?`.
    - Document every public item with a rustdoc comment, and include a `# Errors` section for
      fallible functions and a `# Panics` section for ones that can panic. Examples in docs are
      compiled and tested — they double as regression tests.
    
    ## Size and structure
    
    These are conventions, not compiler limits — but they track real maintainability, and
    clippy enforces the function one by default.
    
    | Scope             | Practical target        | Basis |
    |-------------------|-------------------------|-------|
    | Function / method | **≤ 100 lines**         | clippy `too_many_lines` default threshold is 100. |
    | `.rs` file / module | **≤ ~1,000 lines**    | No compiler/clippy limit; a common team convention. Split by responsibility. |
    | Crate             | **No line cap**         | Split around a real API / domain / dependency boundary, not a line count. |
    | Published `.crate`| **≤ 10 MB compressed**  | crates.io hard limit on the packaged archive. |
    
    Exceptions that legitimately blow past the file target: generated code, large lookup
    tables/fixtures, and macro-heavy modules. When a function crosses ~100 lines, the fix is
    almost always to extract a well-named helper, not to `#[allow]` the lint — the name you give
    the extracted piece is documentation.
    
    Organize modules by responsibility, not by type-kind (`mod users` beats a `mod structs`).
    Keep the crate's public surface in `lib.rs`/`mod.rs` re-exports so callers have one obvious
    import path.
    
    ## Unsafe
    
    - Default to safe Rust. Reach for `unsafe` only for FFI, genuine performance-critical spots
      proven by measurement, or building a safe abstraction over a raw operation.
    - Every `unsafe` block gets a `// SAFETY:` comment stating the invariant that makes it sound.
      Keep unsafe blocks minimal and wrapped in a safe API so the unsafety doesn't leak.
    
    ## Dependencies
    
    - Add a dependency when it earns its keep; each one is compile time, audit surface, and a
      future upgrade. Prefer well-maintained, widely-used crates.
    - Use precise-enough version requirements, keep `Cargo.lock` committed for binaries, and run
      `cargo update` deliberately. Consider `cargo deny` / `cargo audit` for license and
      vulnerability checks on anything shipped.
    - Fill in `Cargo.toml` metadata for published crates (description, license, repository,
      keywords, categories) — C-METADATA.
    
    ## Testing
    
    - Unit tests live in a `#[cfg(test)] mod tests` beside the code; integration tests go in
      `tests/`. Test behavior and edge cases, not just the happy path.
    - Prefer table-driven tests for multiple input/output cases. Use `assert_eq!` with meaningful
      values so failures are legible.
    - Doctests keep examples honest — put a runnable example on public functions.
    - For parsing/serialization and anything with an input space, consider property tests
      (`proptest`/`quickcheck`).
    
    ## Async (when it applies)
    
    - Don't block in async code (`std::fs`, `std::thread::sleep`, long CPU loops) — it stalls the
      executor. Use the async equivalents or `spawn_blocking`.
    - Don't hold a `std::sync::Mutex` guard across an `.await`. Use an async-aware lock or drop the
      guard first.
    - Don't add `async` to a function that never awaits.
    
    ## Applying this in a review
    
    When reviewing Rust rather than writing it, scan in this order — it surfaces the highest-value
    issues first: (1) `unwrap`/`expect`/`panic!` on fallible or input-driven paths; (2) error
    handling that discards context or matches-to-re-return instead of `?`; (3) needless `clone`s
    and overly-specific parameter types; (4) missing `Debug`/derives on public types and missing
    docs on public items; (5) oversized functions that should be split; (6) any `unsafe` without a
    `// SAFETY:` justification. Point to `path:line`, say which failure the issue invites, and
    prefer suggesting the idiomatic shape over just naming the rule.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.