rust-skills

name	rust-skills
description	Comprehensive Rust coding guidelines with 179 rules across 14 categories. Use when writing, reviewing, or refactoring Rust code. Covers ownership, error handling, async patterns, API design, memory optimization, performance, testing, and common anti-patterns. Invoke with /rust-skills.
license	MIT
metadata	{"author":"leonardomso","version":"1.0.0","sources":["Rust API Guidelines","Rust Performance Book","ripgrep, tokio, serde, polars codebases"]}

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

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

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

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)
• - Implement for sensible defaults

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 for latest-value sharing

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

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

---

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

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)