🇺🇸English

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

---

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 for conditional ownership

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

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
• - Use instead of when fixed

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
• - Use extension traits to add methods to foreign types

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 not in async code

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

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

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

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
• - Structure tests as arrange/act/assert

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

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 to reuse allocations

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 for internal APIs

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

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
• - Don't accept when works

---

Recommended Cargo.toml Settings

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

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

Rule Application by Task

---

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)

Weekly Installs

411

Repository

leonardomso/rust-skills

GitHub Stars

103

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykWarn

Installed on

opencode364

codex353

gemini-cli346

github-copilot335

kimi-cli302

amp301