Rust Best Practices

Comprehensive guide for writing high-quality, idiomatic, and highly optimized Rust code. Contains 179 rules across 14 categories, prioritized by impact to guide LLMs in code generation and refactoring.

When to Apply

Reference these guidelines when:

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

Rule Categories by Priority


own-
err-
mem-
api-
async-
opt-
name-
type-
test-
doc-
perf-
proj-
lint-
anti-

Priority	Category	Impact	Prefix	Rules
1	Ownership & Borrowing	CRITICAL	`own-`	12
2	Error Handling	CRITICAL	`err-`	12
3	Memory Optimization	CRITICAL	`mem-`	15
4	API Design	HIGH	`api-`	15
5	Async/Await	HIGH	`async-`	15
6	Compiler Optimization	HIGH	`opt-`	12
7	Naming Conventions	MEDIUM	`name-`	16
8	Type Safety	MEDIUM	`type-`	10
9	Testing	MEDIUM	`test-`	13
10	Documentation	MEDIUM	`doc-`	11
11	Performance Patterns	MEDIUM	`perf-`	11
12	Project Structure	LOW	`proj-`	11
13	Clippy & Linting	LOW	`lint-`	11
14	Anti-patterns	REFERENCE	`anti-`	15

Quick Reference

1. Ownership & Borrowing (CRITICAL)

```
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

2. Error Handling (CRITICAL)

```
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()

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

3. Memory Optimization (CRITICAL)

```
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

4. API Design (HIGH)

```
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

5. Async/Await (HIGH)

```
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

6. Compiler Optimization (HIGH)

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

7. Naming Conventions (MEDIUM)

```
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

8. Type Safety (MEDIUM)

```
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

9. Testing (MEDIUM)

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

10. Documentation (MEDIUM)

```
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

11. Performance Patterns (MEDIUM)

```
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

12. Project Structure (LOW)

```
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

13. Clippy & Linting (LOW)

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

14. Anti-patterns (REFERENCE)

```
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

Recommended Cargo.toml Settings

toml

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

[profile.bench]
inherits = "release"
debug = true
strip = false

[profile.dev]
opt-level = 0
debug = true

[profile.dev.package."*"]
opt-level = 3  # Optimize dependencies in dev

How to Use

This skill provides rule identifiers for quick reference. When generating or reviewing Rust code:

Check relevant category based on task type
Apply rules with matching prefix
Prioritize CRITICAL > HIGH > MEDIUM > LOW
Read rule files in
```
rules/
```
for detailed examples

Rule Application by Task

Task	Primary Categories
New function	`own-` , `err-` , `name-`
New struct/API	`api-` , `type-` , `doc-`
Async code	`async-` , `own-`
Error handling	`err-` , `api-`
Memory optimization	`mem-` , `own-` , `perf-`
Performance tuning	`opt-` , `mem-` , `perf-`
Code review	`anti-` , `lint-`

Sources

This skill synthesizes best practices from:

Rust API Guidelines
Rust Performance Book
Rust Design Patterns
Production codebases: ripgrep, tokio, serde, polars, axum, deno
Clippy lint documentation
Community conventions (2024-2025)

rust-skills

NPX Install

Tags

SKILL.md Content

Rust Best Practices

When to Apply

Rule Categories by Priority

Quick Reference

1. Ownership & Borrowing (CRITICAL)

2. Error Handling (CRITICAL)

3. Memory Optimization (CRITICAL)

4. API Design (HIGH)

5. Async/Await (HIGH)

6. Compiler Optimization (HIGH)

7. Naming Conventions (MEDIUM)

8. Type Safety (MEDIUM)

9. Testing (MEDIUM)

10. Documentation (MEDIUM)

11. Performance Patterns (MEDIUM)

12. Project Structure (LOW)

13. Clippy & Linting (LOW)

14. Anti-patterns (REFERENCE)

Recommended Cargo.toml Settings

How to Use

Rule Application by Task

Sources