Rust Core
Comprehensive guide for writing high-quality, idiomatic, and optimized Rust code. Targets Rust 1.80+ and Edition 2024.
When to Apply
- Writing new Rust functions, structs, or modules
- Implementing error handling or async 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
- Fixing compiler errors (see references/compiler-errors.md)
Edition 2024 Changes (Rust 1.85+)
| Change |
Impact |
Action |
unsafe blocks required for extern blocks |
extern "C" { ... } now needs unsafe { extern "C" { ... } } |
Wrap extern blocks in unsafe |
unsafe_op_in_unsafe_fn lint |
unsafe fn body requires explicit unsafe blocks for unsafe ops |
Add unsafe { ... } inside unsafe fns |
if let temporary scope |
Temporaries dropped at end of if let block |
May extend borrow lifetimes |
gen keyword reserved |
gen { ... } blocks for iterators |
Use gen for lazy iterators |
#[diagnostic::on_unimplemented] |
Better error messages for trait failures |
Add to library traits |
| Nested or-patterns |
Some(1 | 2) stabilized |
Use in match arms |
Run cargo fix --edition to apply most changes automatically.
Rule Categories by Priority
| Priority |
Category |
Prefix |
Rules |
| 1 |
Ownership & Borrowing |
own- |
12 |
| 2 |
Error Handling |
err- |
12 |
| 3 |
Memory Optimization |
mem- |
15 |
| 4 |
API Design |
api- |
15 |
| 5 |
Async/Await |
async- |
15 |
| 6 |
Compiler Optimization |
opt- |
12 |
| 7 |
Naming Conventions |
name- |
16 |
| 8 |
Type Safety |
type- |
10 |
| 9 |
Testing |
test- |
13 |
| 10 |
Documentation |
doc- |
11 |
| 11 |
Performance Patterns |
perf- |
11 |
| 12 |
Project Structure |
proj- |
11 |
| 13 |
Clippy & Linting |
lint- |
11 |
| 14 |
Anti-patterns |
anti- |
15 |
Detailed rules live in rules/ — 14 files, one per prefix group (ownership.md covers own-, error-handling.md covers err-, …). Each ## <rule-id> section inside a category file is one rule, so a grep for a rule id lands directly on it.
Rule Index
Ownership & Borrowing (own-)
| Rule |
Description |
own-borrow-over-clone |
Prefer &T borrowing over .clone() |
own-slice-over-vec |
Accept &[T] not &Vec<T>, &str not &String |
own-cow-conditional |
Use Cow<'a, T> for conditional ownership |
own-arc-shared |
Use Arc<T> for thread-safe shared ownership |
own-rc-single-thread |
Use Rc<T> for single-threaded sharing |
own-refcell-interior |
Use RefCell<T> for interior mutability (single-thread) |
own-mutex-interior |
Use Mutex<T> for interior mutability (multi-thread) |
own-rwlock-readers |
Use RwLock<T> when reads dominate writes |
own-copy-small |
Derive Copy for small, trivial types |
own-clone-explicit |
Make Clone explicit, avoid implicit copies |
own-move-large |
Move large data instead of cloning |
own-lifetime-elision |
Rely on lifetime elision when possible |
Error Handling (err-)
| Rule |
Description |
err-thiserror-lib |
Use thiserror for library error types |
err-anyhow-app |
Use anyhow for application error handling |
err-result-over-panic |
Return Result, don't panic on expected errors |
err-context-chain |
Add context with .context() or .with_context() |
err-no-unwrap-prod |
Never use .unwrap() in production code |
err-expect-bugs-only |
Use .expect() only for programming errors |
err-question-mark |
Use ? operator for clean propagation |
err-from-impl |
Use #[from] for automatic error conversion |
err-source-chain |
Use #[source] to chain underlying errors |
err-lowercase-msg |
Error messages: lowercase, no trailing punctuation |
err-doc-errors |
Document errors with # Errors section |
err-custom-type |
Create custom error types, not Box<dyn Error> |
Memory Optimization (mem-)
| Rule |
Description |
mem-with-capacity |
Use with_capacity() when size is known |
mem-smallvec |
Use SmallVec for usually-small collections |
mem-arrayvec |
Use ArrayVec for bounded-size collections |
mem-box-large-variant |
Box large enum variants to reduce type size |
mem-boxed-slice |
Use Box<[T]> instead of Vec<T> when fixed |
mem-thinvec |
Use ThinVec for often-empty vectors |
mem-clone-from |
Use clone_from() to reuse allocations |
mem-reuse-collections |
Reuse collections with clear() in loops |
mem-avoid-format |
Avoid format!() when string literals work |
mem-write-over-format |
Use write!() instead of format!() |
mem-arena-allocator |
Use arena allocators for batch allocations |
mem-zero-copy |
Use zero-copy patterns with slices and Bytes |
mem-compact-string |
Use CompactString for small string optimization |
mem-smaller-integers |
Use smallest integer type that fits |
mem-assert-type-size |
Assert hot type sizes to prevent regressions |
API Design (api-)
| Rule |
Description |
api-builder-pattern |
Use Builder pattern for complex construction |
api-builder-must-use |
Add #[must_use] to builder types |
api-newtype-safety |
Use newtypes for type-safe distinctions |
api-typestate |
Use typestate for compile-time state machines |
api-sealed-trait |
Seal traits to prevent external implementations |
api-extension-trait |
Use extension traits to add methods to foreign types |
api-parse-dont-validate |
Parse into validated types at boundaries |
api-impl-into |
Accept impl Into<T> for flexible string inputs |
api-impl-asref |
Accept impl AsRef<T> for borrowed inputs |
api-must-use |
Add #[must_use] to Result-returning functions |
api-non-exhaustive |
Use #[non_exhaustive] for future-proof enums/structs |
api-from-not-into |
Implement From, not Into (auto-derived) |
api-default-impl |
Implement Default for sensible defaults |
api-common-traits |
Implement Debug, Clone, PartialEq eagerly |
api-serde-optional |
Gate Serialize/Deserialize behind feature flag |
Async/Await (async-)
| Rule |
Description |
async-tokio-runtime |
Use Tokio for production async runtime |
async-no-lock-await |
Never hold Mutex/RwLock across .await |
async-spawn-blocking |
Use spawn_blocking for CPU-intensive work |
async-tokio-fs |
Use tokio::fs not std::fs in async code |
async-cancellation-token |
Use CancellationToken for graceful shutdown |
async-join-parallel |
Use tokio::join! for parallel operations |
async-try-join |
Use tokio::try_join! for fallible parallel ops |
async-select-racing |
Use tokio::select! for racing/timeouts |
async-bounded-channel |
Use bounded channels for backpressure |
async-mpsc-queue |
Use mpsc for work queues |
async-broadcast-pubsub |
Use broadcast for pub/sub patterns |
async-watch-latest |
Use watch for latest-value sharing |
async-oneshot-response |
Use oneshot for request/response |
async-joinset-structured |
Use JoinSet for dynamic task groups |
async-clone-before-await |
Clone data before await, release locks |
Compiler Optimization (opt-)
| Rule |
Description |
opt-inline-small |
Use #[inline] for small hot functions |
opt-inline-always-rare |
Use #[inline(always)] sparingly |
opt-inline-never-cold |
Use #[inline(never)] for cold paths |
opt-cold-unlikely |
Use #[cold] for error/unlikely paths |
opt-likely-hint |
Use likely()/unlikely() for branch hints |
opt-lto-release |
Enable LTO in release builds |
opt-codegen-units |
Use codegen-units = 1 for max optimization |
opt-pgo-profile |
Use PGO for production builds |
opt-target-cpu |
Set target-cpu=native for local builds |
opt-bounds-check |
Use iterators to avoid bounds checks |
opt-simd-portable |
Use portable SIMD for data-parallel ops |
opt-cache-friendly |
Design cache-friendly data layouts (SoA) |
Naming Conventions (name-)
| Rule |
Description |
name-types-camel |
Use UpperCamelCase for types, traits, enums |
name-variants-camel |
Use UpperCamelCase for enum variants |
name-funcs-snake |
Use snake_case for functions, methods, modules |
name-consts-screaming |
Use SCREAMING_SNAKE_CASE for constants/statics |
name-lifetime-short |
Use short lowercase lifetimes: 'a, 'de, 'src |
name-type-param-single |
Use single uppercase for type params: T, E, K, V |
name-as-free |
as_ prefix: free reference conversion |
name-to-expensive |
to_ prefix: expensive conversion |
name-into-ownership |
into_ prefix: ownership transfer |
name-no-get-prefix |
No get_ prefix for simple getters |
name-is-has-bool |
Use is_, has_, can_ for boolean methods |
name-iter-convention |
Use iter/iter_mut/into_iter for iterators |
name-iter-method |
Name iterator methods consistently |
name-iter-type-match |
Iterator type names match method |
name-acronym-word |
Treat acronyms as words: Uuid not UUID |
name-crate-no-rs |
Crate names: no -rs suffix |
Type Safety (type-)
| Rule |
Description |
type-newtype-ids |
Wrap IDs in newtypes: UserId(u64) |
type-newtype-validated |
Newtypes for validated data: Email, Url |
type-enum-states |
Use enums for mutually exclusive states |
type-option-nullable |
Use Option<T> for nullable values |
type-result-fallible |
Use Result<T, E> for fallible operations |
type-phantom-marker |
Use PhantomData<T> for type-level markers |
type-never-diverge |
Use ! type for functions that never return |
type-generic-bounds |
Add trait bounds only where needed |
type-no-stringly |
Avoid stringly-typed APIs, use enums/newtypes |
type-repr-transparent |
Use #[repr(transparent)] for FFI newtypes |
Testing (test-)
| Rule |
Description |
test-cfg-test-module |
Use #[cfg(test)] mod tests { } |
test-use-super |
Use use super::*; in test modules |
test-integration-dir |
Put integration tests in tests/ directory |
test-descriptive-names |
Use descriptive test names |
test-arrange-act-assert |
Structure tests as arrange/act/assert |
test-proptest-properties |
Use proptest for property-based testing |
test-mockall-mocking |
Use mockall for trait mocking |
test-mock-traits |
Use traits for dependencies to enable mocking |
test-fixture-raii |
Use RAII pattern (Drop) for test cleanup |
test-tokio-async |
Use #[tokio::test] for async tests |
test-should-panic |
Use #[should_panic] for panic tests |
test-criterion-bench |
Use criterion for benchmarking |
test-doctest-examples |
Keep doc examples as executable tests |
Documentation (doc-)
| Rule |
Description |
doc-all-public |
Document all public items with /// |
doc-module-inner |
Use //! for module-level documentation |
doc-examples-section |
Include # Examples with runnable code |
doc-errors-section |
Include # Errors for fallible functions |
doc-panics-section |
Include # Panics for panicking functions |
doc-safety-section |
Include # Safety for unsafe functions |
doc-question-mark |
Use ? in examples, not .unwrap() |
doc-hidden-setup |
Use # prefix to hide example setup code |
doc-intra-links |
Use intra-doc links: [Vec] |
doc-link-types |
Link related types and functions in docs |
doc-cargo-metadata |
Fill Cargo.toml metadata |
Performance Patterns (perf-)
| Rule |
Description |
perf-iter-over-index |
Prefer iterators over manual indexing |
perf-iter-lazy |
Keep iterators lazy, collect() only when needed |
perf-collect-once |
Don't collect() intermediate iterators |
perf-entry-api |
Use entry() API for map insert-or-update |
perf-drain-reuse |
Use drain() to reuse allocations |
perf-extend-batch |
Use extend() for batch insertions |
perf-chain-avoid |
Avoid chain() in hot loops |
perf-collect-into |
Use collect_into() for reusing containers |
perf-black-box-bench |
Use black_box() in benchmarks |
perf-release-profile |
Optimize release profile settings |
perf-profile-first |
Profile before optimizing |
Project Structure (proj-)
| Rule |
Description |
proj-lib-main-split |
Keep main.rs minimal, logic in lib.rs |
proj-mod-by-feature |
Organize modules by feature, not type |
proj-flat-small |
Keep small projects flat |
proj-mod-rs-dir |
Use mod.rs for multi-file modules |
proj-pub-crate-internal |
Use pub(crate) for internal APIs |
proj-pub-super-parent |
Use pub(super) for parent-only visibility |
proj-pub-use-reexport |
Use pub use for clean public API |
proj-prelude-module |
Create prelude module for common imports |
proj-bin-dir |
Put multiple binaries in src/bin/ |
proj-workspace-large |
Use workspaces for large projects |
proj-workspace-deps |
Use workspace dependency inheritance |
Clippy & Linting (lint-)
| Rule |
Description |
lint-deny-correctness |
#![deny(clippy::correctness)] |
lint-warn-suspicious |
#![warn(clippy::suspicious)] |
lint-warn-style |
#![warn(clippy::style)] |
lint-warn-complexity |
#![warn(clippy::complexity)] |
lint-warn-perf |
#![warn(clippy::perf)] |
lint-pedantic-selective |
Enable clippy::pedantic selectively |
lint-missing-docs |
#![warn(missing_docs)] |
lint-unsafe-doc |
#![warn(clippy::undocumented_unsafe_blocks)] |
lint-cargo-metadata |
#![warn(clippy::cargo)] for published crates |
lint-rustfmt-check |
Run cargo fmt --check in CI |
lint-workspace-lints |
Configure lints at workspace level |
Anti-patterns (anti-)
| Rule |
Description |
anti-unwrap-abuse |
Don't use .unwrap() in production code |
anti-expect-lazy |
Don't use .expect() for recoverable errors |
anti-clone-excessive |
Don't clone when borrowing works |
anti-lock-across-await |
Don't hold locks across .await |
anti-string-for-str |
Don't accept &String when &str works |
anti-vec-for-slice |
Don't accept &Vec<T> when &[T] works |
anti-index-over-iter |
Don't use indexing when iterators work |
anti-panic-expected |
Don't panic on expected/recoverable errors |
anti-empty-catch |
Don't use empty if let Err(_) = ... blocks |
anti-over-abstraction |
Don't over-abstract with excessive generics |
anti-premature-optimize |
Don't optimize before profiling |
anti-type-erasure |
Don't use Box<dyn Trait> when impl Trait works |
anti-format-hot-path |
Don't use format!() in hot paths |
anti-collect-intermediate |
Don't collect() intermediate iterators |
anti-stringly-typed |
Don't use strings for structured data |
Ownership & Borrowing
- Prefer
&T borrowing over .clone()
- Accept
&[T] not &Vec<T>, &str not &String
- Use
Cow<'a, T> for conditional ownership
- Use
Arc<T> for thread-safe shared ownership, Rc<T> for single-threaded
- Use
RefCell<T> (single-thread) or Mutex<T>/RwLock<T> (multi-thread) for interior mutability
- Derive
Copy for small, trivial types
- Move large data instead of cloning
- Rely on lifetime elision when possible
Error Handling
- Use
thiserror for library error types, anyhow for application error handling
- Return
Result, don't panic on expected errors
- Add context with
.context() or .with_context()
- Never use
.unwrap() in production code
- Use
.expect() only for programming errors
- Use
? operator for clean propagation
- Use
#[from] for automatic error conversion
- Use
#[source] to chain underlying errors
- Error messages: lowercase, no trailing punctuation
- Document errors with
# Errors section
- Create custom error types, not
Box<dyn Error>
Memory Optimization
- Use
with_capacity() when size is known
- Use
SmallVec for usually-small collections, ArrayVec for bounded-size
- Box large enum variants to reduce type size
- Use
Box<[T]> instead of Vec<T> when fixed size
- Use
clone_from() to reuse allocations
- Reuse collections with
clear() in loops
- Avoid
format!() when string literals work; use write!() instead
- Use smallest integer type that fits
- Assert hot type sizes to prevent regressions
API Design
- Use Builder pattern for complex construction; add
#[must_use] to builder types
- Use newtypes for type-safe distinctions (
UserId(u64), Email, Url)
- Use typestate for compile-time state machines
- Seal traits to prevent external implementations when appropriate
- Use extension traits to add methods to foreign types
- Parse into validated types at boundaries
- Accept
impl Into<T> for flexible string inputs, impl AsRef<T> for borrowed inputs
- Add
#[must_use] to Result-returning functions
- Use
#[non_exhaustive] for future-proof enums/structs
- Implement
From, not Into (auto-derived)
- Implement
Default for sensible defaults
- Implement
Debug, Clone, PartialEq eagerly
- Gate
Serialize/Deserialize behind feature flag
Async/Await
- Use Tokio for production async runtime
- Never hold
Mutex/RwLock across .await
- Use
spawn_blocking for CPU-intensive work
- Use
tokio::fs not std::fs in async code
- Use
CancellationToken for graceful shutdown
- Use
tokio::join! for parallel operations, tokio::try_join! for fallible
- Use
tokio::select! for racing/timeouts
- Use bounded channels for backpressure
- Use
JoinSet for dynamic task groups
- Clone data before await, release locks
Testing
- Use
#[cfg(test)] mod tests { } with use super::*;
- Put integration tests in
tests/ directory
- Structure tests as arrange/act/assert
- Use
#[tokio::test] for async tests
- Use
proptest for property-based testing
- Use
mockall for trait mocking; design dependencies as traits
- Use RAII pattern (Drop) for test cleanup
- Use
criterion for benchmarking
- Keep doc examples as executable tests
- Use
#[should_panic] for panic tests
- Aim for 80%+ coverage; test edge cases and error paths
Anti-Patterns
The 15 anti-* rules are indexed in the Rule Index above with full rationale and ❌/✅ examples in rules/anti-patterns.md.
Essential Commands
cargo build --release # Build with optimizations
cargo test # Run all tests
cargo test -- --nocapture # Run tests with output
cargo clippy -- -D warnings # Lint with warnings as errors
cargo fmt --check # Check formatting
cargo doc --no-deps # Generate documentation
cargo bench # Run benchmarks
cargo fix --edition # Auto-fix edition migration
Cargo.toml Release Profile
[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true
[profile.dev.package."*"]
opt-level = 3
References
rules/ — 14 category files (179 rules total), one file per prefix group, read on demand
references/compiler-errors.md — Compiler error quick reference (E0382, E0502, E0716, etc.)
1---2name: rust-core3description: >4 Use when writing, reviewing, or refactoring Rust code. Covers ownership,5 borrowing, error handling, async patterns, API design, memory optimization,6 performance, testing, and common anti-patterns. Targets Rust 1.80+ and7 Edition 2024. Invoke with /rust-core.8globs: ["**/*.rs"]9license: MIT10metadata:11 source: https://skillmd.com/skills/mte90/rust-core12 author: mte9013 version: "2.0.0"14 tags:15 - rust16 - core17 - ownership18 - error-handling19 - async20 - performance21 - testing22 sources:23 - Rust API Guidelines24 - Rust Performance Book25 - Rust Design Patterns26 - ripgrep, tokio, serde, polars codebases27---2829# Rust Core3031Comprehensive guide for writing high-quality, idiomatic, and optimized Rust code. Targets Rust 1.80+ and Edition 2024.3233## When to Apply3435- Writing new Rust functions, structs, or modules36- Implementing error handling or async code37- Designing public APIs for libraries38- Reviewing code for ownership/borrowing issues39- Optimizing memory usage or reducing allocations40- Tuning performance for hot paths41- Refactoring existing Rust code42- Fixing compiler errors (see [references/compiler-errors.md](references/compiler-errors.md))4344## Edition 2024 Changes (Rust 1.85+)4546| Change | Impact | Action |47|--------|--------|--------|48| `unsafe` blocks required for `extern` blocks | `extern "C" { ... }` now needs `unsafe { extern "C" { ... } }` | Wrap extern blocks in `unsafe` |49| `unsafe_op_in_unsafe_fn` lint | `unsafe fn` body requires explicit `unsafe` blocks for unsafe ops | Add `unsafe { ... }` inside unsafe fns |50| `if let` temporary scope | Temporaries dropped at end of `if let` block | May extend borrow lifetimes |51| `gen` keyword reserved | `gen { ... }` blocks for iterators | Use `gen` for lazy iterators |52| `#[diagnostic::on_unimplemented]` | Better error messages for trait failures | Add to library traits |53| Nested or-patterns | `Some(1 \| 2)` stabilized | Use in match arms |5455Run `cargo fix --edition` to apply most changes automatically.5657## Rule Categories by Priority5859| Priority | Category | Prefix | Rules |60|----------|----------|--------|-------|61| 1 | Ownership & Borrowing | `own-` | 12 |62| 2 | Error Handling | `err-` | 12 |63| 3 | Memory Optimization | `mem-` | 15 |64| 4 | API Design | `api-` | 15 |65| 5 | Async/Await | `async-` | 15 |66| 6 | Compiler Optimization | `opt-` | 12 |67| 7 | Naming Conventions | `name-` | 16 |68| 8 | Type Safety | `type-` | 10 |69| 9 | Testing | `test-` | 13 |70| 10 | Documentation | `doc-` | 11 |71| 11 | Performance Patterns | `perf-` | 11 |72| 12 | Project Structure | `proj-` | 11 |73| 13 | Clippy & Linting | `lint-` | 11 |74| 14 | Anti-patterns | `anti-` | 15 |7576Detailed rules live in `rules/` — 14 files, one per prefix group (`ownership.md` covers `own-`, `error-handling.md` covers `err-`, …). Each `## <rule-id>` section inside a category file is one rule, so a grep for a rule id lands directly on it.7778## Rule Index7980### Ownership & Borrowing (`own-`)8182| Rule | Description |83|------|-------------|84| `own-borrow-over-clone` | Prefer `&T` borrowing over `.clone()` |85| `own-slice-over-vec` | Accept `&[T]` not `&Vec<T>`, `&str` not `&String` |86| `own-cow-conditional` | Use `Cow<'a, T>` for conditional ownership |87| `own-arc-shared` | Use `Arc<T>` for thread-safe shared ownership |88| `own-rc-single-thread` | Use `Rc<T>` for single-threaded sharing |89| `own-refcell-interior` | Use `RefCell<T>` for interior mutability (single-thread) |90| `own-mutex-interior` | Use `Mutex<T>` for interior mutability (multi-thread) |91| `own-rwlock-readers` | Use `RwLock<T>` when reads dominate writes |92| `own-copy-small` | Derive `Copy` for small, trivial types |93| `own-clone-explicit` | Make `Clone` explicit, avoid implicit copies |94| `own-move-large` | Move large data instead of cloning |95| `own-lifetime-elision` | Rely on lifetime elision when possible |9697### Error Handling (`err-`)9899| Rule | Description |100|------|-------------|101| `err-thiserror-lib` | Use `thiserror` for library error types |102| `err-anyhow-app` | Use `anyhow` for application error handling |103| `err-result-over-panic` | Return `Result`, don't panic on expected errors |104| `err-context-chain` | Add context with `.context()` or `.with_context()` |105| `err-no-unwrap-prod` | Never use `.unwrap()` in production code |106| `err-expect-bugs-only` | Use `.expect()` only for programming errors |107| `err-question-mark` | Use `?` operator for clean propagation |108| `err-from-impl` | Use `#[from]` for automatic error conversion |109| `err-source-chain` | Use `#[source]` to chain underlying errors |110| `err-lowercase-msg` | Error messages: lowercase, no trailing punctuation |111| `err-doc-errors` | Document errors with `# Errors` section |112| `err-custom-type` | Create custom error types, not `Box<dyn Error>` |113114### Memory Optimization (`mem-`)115116| Rule | Description |117|------|-------------|118| `mem-with-capacity` | Use `with_capacity()` when size is known |119| `mem-smallvec` | Use `SmallVec` for usually-small collections |120| `mem-arrayvec` | Use `ArrayVec` for bounded-size collections |121| `mem-box-large-variant` | Box large enum variants to reduce type size |122| `mem-boxed-slice` | Use `Box<[T]>` instead of `Vec<T>` when fixed |123| `mem-thinvec` | Use `ThinVec` for often-empty vectors |124| `mem-clone-from` | Use `clone_from()` to reuse allocations |125| `mem-reuse-collections` | Reuse collections with `clear()` in loops |126| `mem-avoid-format` | Avoid `format!()` when string literals work |127| `mem-write-over-format` | Use `write!()` instead of `format!()` |128| `mem-arena-allocator` | Use arena allocators for batch allocations |129| `mem-zero-copy` | Use zero-copy patterns with slices and `Bytes` |130| `mem-compact-string` | Use `CompactString` for small string optimization |131| `mem-smaller-integers` | Use smallest integer type that fits |132| `mem-assert-type-size` | Assert hot type sizes to prevent regressions |133134### API Design (`api-`)135136| Rule | Description |137|------|-------------|138| `api-builder-pattern` | Use Builder pattern for complex construction |139| `api-builder-must-use` | Add `#[must_use]` to builder types |140| `api-newtype-safety` | Use newtypes for type-safe distinctions |141| `api-typestate` | Use typestate for compile-time state machines |142| `api-sealed-trait` | Seal traits to prevent external implementations |143| `api-extension-trait` | Use extension traits to add methods to foreign types |144| `api-parse-dont-validate` | Parse into validated types at boundaries |145| `api-impl-into` | Accept `impl Into<T>` for flexible string inputs |146| `api-impl-asref` | Accept `impl AsRef<T>` for borrowed inputs |147| `api-must-use` | Add `#[must_use]` to `Result`-returning functions |148| `api-non-exhaustive` | Use `#[non_exhaustive]` for future-proof enums/structs |149| `api-from-not-into` | Implement `From`, not `Into` (auto-derived) |150| `api-default-impl` | Implement `Default` for sensible defaults |151| `api-common-traits` | Implement `Debug`, `Clone`, `PartialEq` eagerly |152| `api-serde-optional` | Gate `Serialize`/`Deserialize` behind feature flag |153154### Async/Await (`async-`)155156| Rule | Description |157|------|-------------|158| `async-tokio-runtime` | Use Tokio for production async runtime |159| `async-no-lock-await` | Never hold `Mutex`/`RwLock` across `.await` |160| `async-spawn-blocking` | Use `spawn_blocking` for CPU-intensive work |161| `async-tokio-fs` | Use `tokio::fs` not `std::fs` in async code |162| `async-cancellation-token` | Use `CancellationToken` for graceful shutdown |163| `async-join-parallel` | Use `tokio::join!` for parallel operations |164| `async-try-join` | Use `tokio::try_join!` for fallible parallel ops |165| `async-select-racing` | Use `tokio::select!` for racing/timeouts |166| `async-bounded-channel` | Use bounded channels for backpressure |167| `async-mpsc-queue` | Use `mpsc` for work queues |168| `async-broadcast-pubsub` | Use `broadcast` for pub/sub patterns |169| `async-watch-latest` | Use `watch` for latest-value sharing |170| `async-oneshot-response` | Use `oneshot` for request/response |171| `async-joinset-structured` | Use `JoinSet` for dynamic task groups |172| `async-clone-before-await` | Clone data before await, release locks |173174### Compiler Optimization (`opt-`)175176| Rule | Description |177|------|-------------|178| `opt-inline-small` | Use `#[inline]` for small hot functions |179| `opt-inline-always-rare` | Use `#[inline(always)]` sparingly |180| `opt-inline-never-cold` | Use `#[inline(never)]` for cold paths |181| `opt-cold-unlikely` | Use `#[cold]` for error/unlikely paths |182| `opt-likely-hint` | Use `likely()`/`unlikely()` for branch hints |183| `opt-lto-release` | Enable LTO in release builds |184| `opt-codegen-units` | Use `codegen-units = 1` for max optimization |185| `opt-pgo-profile` | Use PGO for production builds |186| `opt-target-cpu` | Set `target-cpu=native` for local builds |187| `opt-bounds-check` | Use iterators to avoid bounds checks |188| `opt-simd-portable` | Use portable SIMD for data-parallel ops |189| `opt-cache-friendly` | Design cache-friendly data layouts (SoA) |190191### Naming Conventions (`name-`)192193| Rule | Description |194|------|-------------|195| `name-types-camel` | Use `UpperCamelCase` for types, traits, enums |196| `name-variants-camel` | Use `UpperCamelCase` for enum variants |197| `name-funcs-snake` | Use `snake_case` for functions, methods, modules |198| `name-consts-screaming` | Use `SCREAMING_SNAKE_CASE` for constants/statics |199| `name-lifetime-short` | Use short lowercase lifetimes: `'a`, `'de`, `'src` |200| `name-type-param-single` | Use single uppercase for type params: `T`, `E`, `K`, `V` |201| `name-as-free` | `as_` prefix: free reference conversion |202| `name-to-expensive` | `to_` prefix: expensive conversion |203| `name-into-ownership` | `into_` prefix: ownership transfer |204| `name-no-get-prefix` | No `get_` prefix for simple getters |205| `name-is-has-bool` | Use `is_`, `has_`, `can_` for boolean methods |206| `name-iter-convention` | Use `iter`/`iter_mut`/`into_iter` for iterators |207| `name-iter-method` | Name iterator methods consistently |208| `name-iter-type-match` | Iterator type names match method |209| `name-acronym-word` | Treat acronyms as words: `Uuid` not `UUID` |210| `name-crate-no-rs` | Crate names: no `-rs` suffix |211212### Type Safety (`type-`)213214| Rule | Description |215|------|-------------|216| `type-newtype-ids` | Wrap IDs in newtypes: `UserId(u64)` |217| `type-newtype-validated` | Newtypes for validated data: `Email`, `Url` |218| `type-enum-states` | Use enums for mutually exclusive states |219| `type-option-nullable` | Use `Option<T>` for nullable values |220| `type-result-fallible` | Use `Result<T, E>` for fallible operations |221| `type-phantom-marker` | Use `PhantomData<T>` for type-level markers |222| `type-never-diverge` | Use `!` type for functions that never return |223| `type-generic-bounds` | Add trait bounds only where needed |224| `type-no-stringly` | Avoid stringly-typed APIs, use enums/newtypes |225| `type-repr-transparent` | Use `#[repr(transparent)]` for FFI newtypes |226227### Testing (`test-`)228229| Rule | Description |230|------|-------------|231| `test-cfg-test-module` | Use `#[cfg(test)] mod tests { }` |232| `test-use-super` | Use `use super::*;` in test modules |233| `test-integration-dir` | Put integration tests in `tests/` directory |234| `test-descriptive-names` | Use descriptive test names |235| `test-arrange-act-assert` | Structure tests as arrange/act/assert |236| `test-proptest-properties` | Use `proptest` for property-based testing |237| `test-mockall-mocking` | Use `mockall` for trait mocking |238| `test-mock-traits` | Use traits for dependencies to enable mocking |239| `test-fixture-raii` | Use RAII pattern (Drop) for test cleanup |240| `test-tokio-async` | Use `#[tokio::test]` for async tests |241| `test-should-panic` | Use `#[should_panic]` for panic tests |242| `test-criterion-bench` | Use `criterion` for benchmarking |243| `test-doctest-examples` | Keep doc examples as executable tests |244245### Documentation (`doc-`)246247| Rule | Description |248|------|-------------|249| `doc-all-public` | Document all public items with `///` |250| `doc-module-inner` | Use `//!` for module-level documentation |251| `doc-examples-section` | Include `# Examples` with runnable code |252| `doc-errors-section` | Include `# Errors` for fallible functions |253| `doc-panics-section` | Include `# Panics` for panicking functions |254| `doc-safety-section` | Include `# Safety` for unsafe functions |255| `doc-question-mark` | Use `?` in examples, not `.unwrap()` |256| `doc-hidden-setup` | Use `# ` prefix to hide example setup code |257| `doc-intra-links` | Use intra-doc links: `[Vec]` |258| `doc-link-types` | Link related types and functions in docs |259| `doc-cargo-metadata` | Fill `Cargo.toml` metadata |260261### Performance Patterns (`perf-`)262263| Rule | Description |264|------|-------------|265| `perf-iter-over-index` | Prefer iterators over manual indexing |266| `perf-iter-lazy` | Keep iterators lazy, `collect()` only when needed |267| `perf-collect-once` | Don't `collect()` intermediate iterators |268| `perf-entry-api` | Use `entry()` API for map insert-or-update |269| `perf-drain-reuse` | Use `drain()` to reuse allocations |270| `perf-extend-batch` | Use `extend()` for batch insertions |271| `perf-chain-avoid` | Avoid `chain()` in hot loops |272| `perf-collect-into` | Use `collect_into()` for reusing containers |273| `perf-black-box-bench` | Use `black_box()` in benchmarks |274| `perf-release-profile` | Optimize release profile settings |275| `perf-profile-first` | Profile before optimizing |276277### Project Structure (`proj-`)278279| Rule | Description |280|------|-------------|281| `proj-lib-main-split` | Keep `main.rs` minimal, logic in `lib.rs` |282| `proj-mod-by-feature` | Organize modules by feature, not type |283| `proj-flat-small` | Keep small projects flat |284| `proj-mod-rs-dir` | Use `mod.rs` for multi-file modules |285| `proj-pub-crate-internal` | Use `pub(crate)` for internal APIs |286| `proj-pub-super-parent` | Use `pub(super)` for parent-only visibility |287| `proj-pub-use-reexport` | Use `pub use` for clean public API |288| `proj-prelude-module` | Create `prelude` module for common imports |289| `proj-bin-dir` | Put multiple binaries in `src/bin/` |290| `proj-workspace-large` | Use workspaces for large projects |291| `proj-workspace-deps` | Use workspace dependency inheritance |292293### Clippy & Linting (`lint-`)294295| Rule | Description |296|------|-------------|297| `lint-deny-correctness` | `#![deny(clippy::correctness)]` |298| `lint-warn-suspicious` | `#![warn(clippy::suspicious)]` |299| `lint-warn-style` | `#![warn(clippy::style)]` |300| `lint-warn-complexity` | `#![warn(clippy::complexity)]` |301| `lint-warn-perf` | `#![warn(clippy::perf)]` |302| `lint-pedantic-selective` | Enable `clippy::pedantic` selectively |303| `lint-missing-docs` | `#![warn(missing_docs)]` |304| `lint-unsafe-doc` | `#![warn(clippy::undocumented_unsafe_blocks)]` |305| `lint-cargo-metadata` | `#![warn(clippy::cargo)]` for published crates |306| `lint-rustfmt-check` | Run `cargo fmt --check` in CI |307| `lint-workspace-lints` | Configure lints at workspace level |308309### Anti-patterns (`anti-`)310311| Rule | Description |312|------|-------------|313| `anti-unwrap-abuse` | Don't use `.unwrap()` in production code |314| `anti-expect-lazy` | Don't use `.expect()` for recoverable errors |315| `anti-clone-excessive` | Don't clone when borrowing works |316| `anti-lock-across-await` | Don't hold locks across `.await` |317| `anti-string-for-str` | Don't accept `&String` when `&str` works |318| `anti-vec-for-slice` | Don't accept `&Vec<T>` when `&[T]` works |319| `anti-index-over-iter` | Don't use indexing when iterators work |320| `anti-panic-expected` | Don't panic on expected/recoverable errors |321| `anti-empty-catch` | Don't use empty `if let Err(_) = ...` blocks |322| `anti-over-abstraction` | Don't over-abstract with excessive generics |323| `anti-premature-optimize` | Don't optimize before profiling |324| `anti-type-erasure` | Don't use `Box<dyn Trait>` when `impl Trait` works |325| `anti-format-hot-path` | Don't use `format!()` in hot paths |326| `anti-collect-intermediate` | Don't `collect()` intermediate iterators |327| `anti-stringly-typed` | Don't use strings for structured data |328329## Ownership & Borrowing330331- Prefer `&T` borrowing over `.clone()`332- Accept `&[T]` not `&Vec<T>`, `&str` not `&String`333- Use `Cow<'a, T>` for conditional ownership334- Use `Arc<T>` for thread-safe shared ownership, `Rc<T>` for single-threaded335- Use `RefCell<T>` (single-thread) or `Mutex<T>`/`RwLock<T>` (multi-thread) for interior mutability336- Derive `Copy` for small, trivial types337- Move large data instead of cloning338- Rely on lifetime elision when possible339340## Error Handling341342- Use `thiserror` for library error types, `anyhow` for application error handling343- Return `Result`, don't panic on expected errors344- Add context with `.context()` or `.with_context()`345- Never use `.unwrap()` in production code346- Use `.expect()` only for programming errors347- Use `?` operator for clean propagation348- Use `#[from]` for automatic error conversion349- Use `#[source]` to chain underlying errors350- Error messages: lowercase, no trailing punctuation351- Document errors with `# Errors` section352- Create custom error types, not `Box<dyn Error>`353354## Memory Optimization355356- Use `with_capacity()` when size is known357- Use `SmallVec` for usually-small collections, `ArrayVec` for bounded-size358- Box large enum variants to reduce type size359- Use `Box<[T]>` instead of `Vec<T>` when fixed size360- Use `clone_from()` to reuse allocations361- Reuse collections with `clear()` in loops362- Avoid `format!()` when string literals work; use `write!()` instead363- Use smallest integer type that fits364- Assert hot type sizes to prevent regressions365366## API Design367368- Use Builder pattern for complex construction; add `#[must_use]` to builder types369- Use newtypes for type-safe distinctions (`UserId(u64)`, `Email`, `Url`)370- Use typestate for compile-time state machines371- Seal traits to prevent external implementations when appropriate372- Use extension traits to add methods to foreign types373- Parse into validated types at boundaries374- Accept `impl Into<T>` for flexible string inputs, `impl AsRef<T>` for borrowed inputs375- Add `#[must_use]` to `Result`-returning functions376- Use `#[non_exhaustive]` for future-proof enums/structs377- Implement `From`, not `Into` (auto-derived)378- Implement `Default` for sensible defaults379- Implement `Debug`, `Clone`, `PartialEq` eagerly380- Gate `Serialize`/`Deserialize` behind feature flag381382## Async/Await383384- Use Tokio for production async runtime385- Never hold `Mutex`/`RwLock` across `.await`386- Use `spawn_blocking` for CPU-intensive work387- Use `tokio::fs` not `std::fs` in async code388- Use `CancellationToken` for graceful shutdown389- Use `tokio::join!` for parallel operations, `tokio::try_join!` for fallible390- Use `tokio::select!` for racing/timeouts391- Use bounded channels for backpressure392- Use `JoinSet` for dynamic task groups393- Clone data before await, release locks394395## Testing396397- Use `#[cfg(test)] mod tests { }` with `use super::*;`398- Put integration tests in `tests/` directory399- Structure tests as arrange/act/assert400- Use `#[tokio::test]` for async tests401- Use `proptest` for property-based testing402- Use `mockall` for trait mocking; design dependencies as traits403- Use RAII pattern (Drop) for test cleanup404- Use `criterion` for benchmarking405- Keep doc examples as executable tests406- Use `#[should_panic]` for panic tests407- Aim for 80%+ coverage; test edge cases and error paths408409## Anti-Patterns410411The 15 `anti-*` rules are indexed in the Rule Index above with full rationale and ❌/✅ examples in [`rules/anti-patterns.md`](rules/anti-patterns.md).412413## Essential Commands414415```bash416cargo build --release # Build with optimizations417cargo test # Run all tests418cargo test -- --nocapture # Run tests with output419cargo clippy -- -D warnings # Lint with warnings as errors420cargo fmt --check # Check formatting421cargo doc --no-deps # Generate documentation422cargo bench # Run benchmarks423cargo fix --edition # Auto-fix edition migration424```425426## Cargo.toml Release Profile427428```toml429[profile.release]430opt-level = 3431lto = "fat"432codegen-units = 1433panic = "abort"434strip = true435436[profile.dev.package."*"]437opt-level = 3438```439440## References441442- `rules/` — 14 category files (179 rules total), one file per prefix group, read on demand443- `references/compiler-errors.md` — Compiler error quick reference (E0382, E0502, E0716, etc.)