rust-skills

# Rust Best Practices Comprehensive guide for writing high-quality, idiomatic, and highly optimized Rust code. Contains 265 rules across 26 categories, prioritized by impact to guide LLMs in code generation and refactoring. Current for Rust 1.96 (2024 edition). ## Hybrid Mount precedence (read before applying any rule) These rules are generic defaults. This repository's own contracts win wherever they differ. Verify against `CLAUDE.md`, `Cargo.toml`, `clippy.toml`, and the current source before acting. - **Hand-written examples are not this codebase.** Rule examples use `anyhow`, `tracing`, `tokio`, crates and nightly features this project does not depend on. Introducing a new dependency or feature to satisfy a rule is out of scope unless the user asks for it. - **Panics:** `unwrap_used`, `expect_used`, `dbg_macro`, `todo`, `unimplemented` are `deny` at workspace level, but `clippy.toml` sets `allow-unwrap-in-tests = true` and `allow-expect-in-tests = true`. So `unwrap`/`expect` are denied in production code and fine inside `#[cfg(test)]`; no existing exception may be removed. - **Error handling:** this crate uses `thiserror` with a hand-written `Error` type. Do not migrate to `anyhow` or `Box<dyn Error>`. - **Logging:** use the `log` crate through `src/logging.rs`; the Android target routes it to `android_logger`. Do not introduce `tracing`. - **Async:** this is a synchronous, startup-time binary with no async runtime. `async-*` rules only apply to async code someone actually adds. - **Targets:** cross-compiled for `aarch64-linux-android`, `armv7-linux-androideabi`, and `x86_64-linux-android`. Never apply `target-cpu=native`, PGO, or other host-specific tuning; use the Android guidance in the `hm-rust-android` skill. - **Release profile:** do not add `[profile.release]` settings such as `panic = "abort"` — xtask and the rollback transaction depend on the current behavior. - **Repository rules outrank every rule here,** including the banned symbols in `CLAUDE.md` (`kasumi`, the removed normalization helpers) and the module source-directory read-only invariant. - **Read selectively.** Open only the rule files relevant to the code under review rather than the whole `rules/` directory. **REQUIRED BACKGROUND:** Use `hm-mount-safety-review` for mount, unmount, staging, and rollback changes; it takes precedence. Use `hm-verify` for the authoritative local gate list. ## When to Apply Reference these guidelines when: - Writing new Rust functions, structs, or modules - Implementing error handling or async code - Writing concurrent, parallel, or `unsafe` code - Designing public APIs for libraries - Reviewing code for ownership/borrowing issues - Optimizing memory usage or reducing allocations - Tuning performance for hot paths - Refactoring existing Rust code ## Rule Categories by Priority | Priority | Category | Impact | Prefix | Rules | |----------|----------|--------|--------|-------| | 1 | Ownership & Borrowing | CRITICAL | `own-` | 12 | | 2 | Error Handling | CRITICAL | `err-` | 12 | | 3 | Memory Optimization | CRITICAL | `mem-` | 17 | | 4 | Unsafe Code | CRITICAL | `unsafe-` | 7 | | 5 | API Design | HIGH | `api-` | 17 | | 6 | Async/Await | HIGH | `async-` | 18 | | 7 | Concurrency | HIGH | `conc-` | 4 | | 8 | Compiler Optimization | HIGH | `opt-` | 12 | | 9 | Numeric & Arithmetic Safety | HIGH | `num-` | 5 | | 10 | Type Safety | MEDIUM | `type-` | 13 | | 11 | Trait & Generics Design | MEDIUM | `trait-` | 6 | | 12 | Conversions | MEDIUM | `conv-` | 3 | | 13 | Const & Compile-Time | MEDIUM | `const-` | 4 | | 14 | Serde | MEDIUM | `serde-` | 8 | | 15 | Pattern Matching | MEDIUM | `pat-` | 5 | | 16 | Macros | MEDIUM | `macro-` | 8 | | 17 | Closures | MEDIUM | `closure-` | 5 | | 18 | Collections | MEDIUM | `coll-` | 4 | | 19 | Naming Conventions | MEDIUM | `name-` | 16 | | 20 | Testing | MEDIUM | `test-` | 15 | | 21 | Documentation | MEDIUM | `doc-` | 12 | | 22 | Observability | MEDIUM | `obs-` | 7 | | 23 | Performance Patterns | MEDIUM | `perf-` | 13 | | 24 | Project Structure | LOW | `proj-` | 14 | | 25 | Clippy & Linting | LOW | `lint-` | 13 | | 26 | Anti-patterns | REFERENCE | `anti-` | 15 | --- ## Quick Reference ### 1. Ownership & Borrowing (CRITICAL) - [`own-borrow-over-clone`](rules/own-borrow-over-clone.md) - Prefer `&T` borrowing over `.clone()` - [`own-slice-over-vec`](rules/own-slice-over-vec.md) - Accept `&[T]` not `&Vec<T>`, `&str` not `&String` - [`own-cow-conditional`](rules/own-cow-conditional.md) - Use `Cow<'a, T>` for conditional ownership - [`own-arc-shared`](rules/own-arc-shared.md) - Use `Arc<T>` for thread-safe shared ownership - [`own-rc-single-thread`](rules/own-rc-single-thread.md) - Use `Rc<T>` for shared ownership in single-threaded contexts - [`own-refcell-interior`](rules/own-refcell-interior.md) - Use `RefCell<T>` for interior mutability in single-threaded code - [`own-mutex-interior`](rules/own-mutex-interior.md) - Use `Mutex<T>` for interior mutability across threads - [`own-rwlock-readers`](rules/own-rwlock-readers.md) - Use `RwLock<T>` when reads significantly outnumber writes - [`own-copy-small`](rules/own-copy-small.md) - Implement `Copy` for small, simple types - [`own-clone-explicit`](rules/own-clone-explicit.md) - Use explicit `Clone` for types where copying has meaningful cost - [`own-move-large`](rules/own-move-large.md) - Move large types instead of copying; use `Box` if moves are expensive - [`own-lifetime-elision`](rules/own-lifetime-elision.md) - Rely on lifetime elision rules; add explicit lifetimes only when required ### 2. Error Handling (CRITICAL) - [`err-thiserror-lib`](rules/err-thiserror-lib.md) - Use `thiserror` for library error types - [`err-anyhow-app`](rules/err-anyhow-app.md) - Use `anyhow` for application error handling - [`err-result-over-panic`](rules/err-result-over-panic.md) - Return `Result<T, E>` instead of panicking for recoverable errors - [`err-context-chain`](rules/err-context-chain.md) - Add context with `.context()` or `.with_context()` - [`err-no-unwrap-prod`](rules/err-no-unwrap-prod.md) - Avoid `unwrap()` in production code; use `?`, `expect()`, or handle errors - [`err-expect-bugs-only`](rules/err-expect-bugs-only.md) - Use `expect()` only for invariants that indicate bugs, not user errors - [`err-question-mark`](rules/err-question-mark.md) - Use `?` operator for clean propagation - [`err-from-impl`](rules/err-from-impl.md) - Implement `From<E>` for error conversions to enable `?` operator - [`err-source-chain`](rules/err-source-chain.md) - Preserve error chains with `#[source]` or `source()` method - [`err-lowercase-msg`](rules/err-lowercase-msg.md) - Start error messages lowercase, no trailing punctuation - [`err-doc-errors`](rules/err-doc-errors.md) - Document error conditions with `# Errors` section in doc comments - [`err-custom-type`](rules/err-custom-type.md) - Define custom error types for domain-specific failures ### 3. Memory Optimization (CRITICAL) - [`mem-with-capacity`](rules/mem-with-capacity.md) - Use `with_capacity()` when size is known - [`mem-smallvec`](rules/mem-smallvec.md) - Use `SmallVec` for usually-small collections - [`mem-arrayvec`](rules/mem-arrayvec.md) - Use `ArrayVec<T, N>` for fixed-capacity collections that never heap-allocate - [`mem-box-large-variant`](rules/mem-box-large-variant.md) - Box large enum variants to reduce overall enum size - [`mem-boxed-slice`](rules/mem-boxed-slice.md) - Use `Box<[T]>` instead of `Vec<T>` for fixed-size heap data - [`mem-thinvec`](rules/mem-thinvec.md) - Use `ThinVec<T>` for nullable collections with minimal overhead - [`mem-clone-from`](rules/mem-clone-from.md) - Use `clone_from()` to reuse allocations when repeatedly cloning - [`mem-reuse-collections`](rules/mem-reuse-collections.md) - Clear and reuse collections instead of creating new ones in loops - [`mem-avoid-format`](rules/mem-avoid-format.md) - Avoid `format!()` when string literals work - [`mem-write-over-format`](rules/mem-write-over-format.md) - Use `write!()` into existing buffers instead of `format!()` allocations - [`mem-arena-allocator`](rules/mem-arena-allocator.md) - Use arena allocators for batch allocations - [`mem-zero-copy`](rules/mem-zero-copy.md) - Use zero-copy patterns with slices and `Bytes` - [`mem-compact-string`](rules/mem-compact-string.md) - Use compact string types for memory-constrained string storage - [`mem-smaller-integers`](rules/mem-smaller-integers.md) - Use appropriately-sized integers to reduce memory footprint - [`mem-assert-type-size`](rules/mem-assert-type-size.md) - Use static assertions to guard against accidental type size growth - [`mem-take-replace`](rules/mem-take-replace.md) - Use `mem::take` / `mem::replace` to move a value out of a `&mut` without cloning - [`mem-drop-order`](rules/mem-drop-order.md) - Know and control drop order: struct fields drop top-to-bottom, locals in reverse ### 4. Unsafe Code (CRITICAL) - [`unsafe-safety-comment`](rules/unsafe-safety-comment.md) - Write a `// SAFETY:` comment above every `unsafe` block and a `# Safety` section in every `unsafe fn`. - [`unsafe-minimize-scope`](rules/unsafe-minimize-scope.md) - Keep `unsafe` blocks as small as possible — mark only the operation that requires unsafety, not the surrounding safe code. - [`unsafe-miri-ci`](rules/unsafe-miri-ci.md) - Run `cargo miri test` in CI for every crate that contains `unsafe` code. - [`unsafe-maybeuninit`](rules/unsafe-maybeuninit.md) - Use `MaybeUninit<T>` for uninitialized memory; never use `mem::uninitialized()` or `mem::zeroed()` for types with validity invariants. - [`unsafe-extern-block`](rules/unsafe-extern-block.md) - In Rust 2024, wrap `extern` blocks in `unsafe extern { }` and annotate each item as `safe` or `unsafe`. - [`unsafe-send-sync-manual`](rules/unsafe-send-sync-manual.md) - Document the invariants when manually implementing `Send` or `Sync`; prefer letting the compiler derive them automatically. - [`unsafe-no-mangle-unsafe`](rules/unsafe-no-mangle-unsafe.md) - In Rust 2024, write `#[unsafe(no_mangle)]`, `#[unsafe(export_name = "...")]`, and `#[unsafe(link_section = "...")]` — not the bare attribute forms. ### 5. API Design (HIGH) - [`api-builder-pattern`](rules/api-builder-pattern.md) - Use Builder pattern for complex construction - [`api-builder-must-use`](rules/api-builder-must-use.md) - Mark builder methods with `#[must_use]` to prevent silent drops - [`api-newtype-safety`](rules/api-newtype-safety.md) - Use newtypes to prevent mixing semantically different values - [`api-typestate`](rules/api-typestate.md) - Use typestate pattern to encode state machine invariants in the type system - [`api-sealed-trait`](rules/api-sealed-trait.md) - Use sealed traits to prevent external implementations while allowing use - [`api-extension-trait`](rules/api-extension-trait.md) - Use extension traits to add methods to external types - [`api-parse-dont-validate`](rules/api-parse-dont-validate.md) - Parse into validated types at boundaries - [`api-impl-into`](rules/api-impl-into.md) - Accept `impl Into<T>` for flexible APIs, implement `From<T>` for conversions - [`api-impl-asref`](rules/api-impl-asref.md) - Use `AsRef<T>` when you only need to borrow the inner data - [`api-must-use`](rules/api-must-use.md) - Mark types and functions with `#[must_use]` when ignoring results is likely a bug - [`api-non-exhaustive`](rules/api-non-exhaustive.md) - Use `#[non_exhaustive]` on public enums and structs for forward compatibility - [`api-from-not-into`](rules/api-from-not-into.md) - Implement `From<T>`, not `Into<U>` - From gives you Into for free - [`api-default-impl`](rules/api-default-impl.md) - Implement `Default` for types with sensible default values - [`api-common-traits`](rules/api-common-traits.md) - Implement standard traits (Debug, Clone, PartialEq, etc.) for public types - [`api-serde-optional`](rules/api-serde-optional.md) - Make serde a feature flag, not a hard dependency for library crates