rust-coding

name

rust-coding

description

Write, review, and refactor idiomatic Rust code following community style conventions. Use when working with Rust functions, structs, modules, error handling, async code, concurrency, unsafe code, API design, memory optimization, performance tuning, numeric safety, conversions, serde, pattern matching, macros, closures, observability, testing, or common anti-patterns. Contains 265 rules across 26 categories prioritized by impact.

Rust Coding

Use this skill to produce maintainable, idiomatic, and highly optimized Rust code. Current for Rust 1.96 (2024 edition).

Workflow

1. Identify the code's role first: new function, struct, module, error handling, async code, unsafe block, API design, optimization, or refactoring.
2. Inspect neighboring .rs files for the crate conventions: edition, module structure, error handling style, async runtime, dependency choices, and local patterns.
3. Keep changes scoped. Preserve existing public APIs, feature flags, and module boundaries unless the user asks for a breaking change.
4. Load the relevant rule files from references/ by category prefix:
   • own-* — Ownership & Borrowing (CRITICAL)
   • err-* — Error Handling (CRITICAL)
   • mem-* — Memory Optimization (CRITICAL)
   • unsafe-* — Unsafe Code (CRITICAL)
   • api-* — API Design (HIGH)
   • async-* — Async/Await (HIGH)
   • conc-* — Concurrency (HIGH)
   • opt-* — Compiler Optimization (HIGH)
   • num-* — Numeric Safety (HIGH)
   • type-*, trait-*, conv-*, const-*, serde-*, pat-*, macro-*, closure-*, coll-*, name-*, test-*, doc-*, obs-*, perf-* — Medium priority categories
   • proj-*, lint-* — Low priority categories
   • anti-* — Anti-patterns reference
5. Apply rules by priority: CRITICAL > HIGH > MEDIUM > LOW.
6. Validate with the narrowest useful command before finishing:
   • cargo check for type and borrow checking
   • cargo fmt --check for formatting
   • cargo clippy for linting
   • cargo test for test suites
   • cargo miri test for crates containing unsafe 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 — 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 shared ownership in single-threaded contexts
• own-refcell-interior — Use RefCell<T> for interior mutability in single-threaded code
• own-mutex-interior — Use Mutex<T> for interior mutability across threads
• own-rwlock-readers — Use RwLock<T> when reads significantly outnumber writes
• own-copy-small — Implement Copy for small, simple types
• own-clone-explicit — Use explicit Clone for types where copying has meaningful cost
• own-move-large — Move large types instead of copying; use Box if moves are expensive
• own-lifetime-elision — Rely on lifetime elision rules; add explicit lifetimes only when required

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<T, E> instead of panicking for recoverable errors
• err-context-chain — Add context with .context() or .with_context()
• err-no-unwrap-prod — Avoid unwrap() in production code; use ?, expect(), or handle errors
• err-expect-bugs-only — Use expect() only for invariants that indicate bugs, not user errors
• err-question-mark — Use ? operator for clean propagation
• err-from-impl — Implement From<E> for error conversions to enable ? operator
• err-source-chain — Preserve error chains with #[source] or source() method
• err-lowercase-msg — Start error messages lowercase, no trailing punctuation
• err-doc-errors — Document error conditions with # Errors section in doc comments
• err-custom-type — Define custom error types for domain-specific failures

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<T, N> for fixed-capacity collections that never heap-allocate
• mem-box-large-variant — Box large enum variants to reduce overall enum size
• mem-boxed-slice — Use Box<[T]> instead of Vec<T> for fixed-size heap data
• mem-thinvec — Use ThinVec<T> for nullable collections with minimal overhead
• mem-clone-from — Use clone_from() to reuse allocations when repeatedly cloning
• mem-reuse-collections — Clear and reuse collections instead of creating new ones in loops
• mem-avoid-format — Avoid format!() when string literals work
• mem-write-over-format — Use write!() into existing buffers instead of format!() allocations
• mem-arena-allocator — Use arena allocators for batch allocations
• mem-zero-copy — Use zero-copy patterns with slices and Bytes
• mem-compact-string — Use compact string types for memory-constrained string storage
• mem-smaller-integers — Use appropriately-sized integers to reduce memory footprint
• mem-assert-type-size — Use static assertions to guard against accidental type size growth
• mem-take-replace — Use mem::take / mem::replace to move a value out of a &mut without cloning
• mem-drop-order — Know and control drop order: struct fields drop top-to-bottom, locals in reverse

4. Unsafe Code (CRITICAL)

• unsafe-safety-comment — Write a // SAFETY: comment above every unsafe block and a # Safety section in every unsafe fn
• unsafe-minimize-scope — Keep unsafe blocks as small as possible
• unsafe-miri-ci — Run cargo miri test in CI for every crate that contains unsafe code
• unsafe-maybeuninit — Use MaybeUninit<T> for uninitialized memory; never use mem::uninitialized() or mem::zeroed()
• unsafe-extern-block — In Rust 2024, wrap extern blocks in unsafe extern { }
• unsafe-send-sync-manual — Document invariants when manually implementing Send or Sync
• unsafe-no-mangle-unsafe — Use #[unsafe(no_mangle)] in Rust 2024

5. API Design (HIGH)

• api-builder-pattern — Use Builder pattern for complex construction
• api-builder-must-use — Mark builder methods with #[must_use]
• api-newtype-safety — Use newtypes to prevent mixing semantically different values
• api-typestate — Use typestate pattern to encode state machine invariants in the type system
• api-sealed-trait — Use sealed traits to prevent external implementations while allowing use
• api-extension-trait — Use extension traits to add methods to external types
• api-parse-dont-validate — Parse into validated types at boundaries
• api-impl-into — Accept impl Into<T> for flexible APIs, implement From<T> for conversions
• api-impl-asref — Use AsRef<T> when you only need to borrow the inner data
• api-must-use — Mark types and functions with #[must_use] when ignoring results is likely a bug
• api-non-exhaustive — Use #[non_exhaustive] on public enums and structs
• api-from-not-into — Implement From<T>, not Into<U>
• api-default-impl — Implement Default for types with sensible default values
• api-common-traits — Implement standard traits (Debug, Clone, PartialEq, etc.) for public types
• api-serde-optional — Make serde a feature flag, not a hard dependency
• api-impl-fromiterator — Implement FromIterator, Extend, and IntoIterator
• api-operator-overload — Overload operators only when semantics are natural

6. Async/Await (HIGH)

• async-tokio-runtime — Configure Tokio runtime appropriately
• 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 instead of std::fs in async code
• async-cancellation-token — Use CancellationToken for graceful shutdown
• async-join-parallel — Use join! or try_join! for concurrent independent futures
• async-try-join — Use try_join! for concurrent fallible operations
• async-select-racing — Use select! to race futures
• async-bounded-channel — Use bounded channels for backpressure
• async-mpsc-queue — Use mpsc channels for async message queues
• async-broadcast-pubsub — Use broadcast channel for pub/sub
• async-watch-latest — Use watch channel for sharing the latest value
• async-oneshot-response — Use oneshot channel for request-response
• async-joinset-structured — Use JoinSet for dynamic task collections
• async-clone-before-await — Clone Arc/Rc before await points
• async-fn-in-trait — Use native async fn in traits (stable 1.75)
• async-async-fn-bounds — Use AsyncFn/AsyncFnMut/AsyncFnOnce bounds
• async-cancel-safety — Ensure tokio::select! branches are cancellation-safe

7. Concurrency (HIGH)

• conc-rayon-par-iter — Use rayon's par_iter() for CPU-bound data parallelism
• conc-scoped-threads — Use std::thread::scope to borrow stack data across threads
• conc-atomic-ordering — Use the weakest correct memory Ordering
• conc-thread-local — Prefer thread_local! with Cell/RefCell over static mut

8. 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)] and #[cold] for error paths
• opt-cold-unlikely — Mark unlikely code paths with #[cold]
• opt-likely-hint — Use code structure to hint at likely branches
• opt-lto-release — Enable LTO in release builds
• opt-codegen-units — Set codegen-units = 1 in release builds
• opt-pgo-profile — Use Profile-Guided Optimization
• opt-target-cpu — Use target-cpu=native on known deployment targets
• opt-bounds-check — Eliminate bounds checks in hot paths
• opt-simd-portable — Use portable SIMD
• opt-cache-friendly — Organize data for cache-efficient access

9. Numeric & Arithmetic Safety (HIGH)

• num-overflow-explicit — Handle integer overflow explicitly
• num-cast-try-from — Avoid as for narrowing casts; use From/TryFrom
• num-float-compare — Don't compare floats with ==; use a tolerance
• num-saturating-clamp — Bound values with clamp and saturating arithmetic
• num-nonzero — Use NonZero* types to forbid zero

10. Type Safety (MEDIUM)

• type-newtype-ids — Wrap IDs in newtypes
• type-newtype-validated — Use newtypes to enforce validation
• type-enum-states — Use enums for mutually exclusive states
• type-option-nullable — Use Option<T> for optional values
• type-result-fallible — Use Result<T, E> for fallible operations
• type-phantom-marker — Use PhantomData for type relationships
• type-never-diverge — Use ! (never type) for non-returning functions
• type-generic-bounds — Add trait bounds only where needed
• type-no-stringly — Avoid stringly-typed APIs
• type-repr-transparent — Use #[repr(transparent)] for newtypes in FFI
• type-deref-coercion — Implement Deref/DerefMut only for smart pointers
• type-display-vs-debug — Use Display for user-facing output, Debug for diagnostics
• type-numeric-fmt — Implement numeric formatting traits for newtypes

11. Trait & Generics Design (MEDIUM)

• trait-associated-type-vs-generic — Associated type vs generic parameter
• trait-blanket-impl — Use blanket impls
• trait-coherence-newtype — Respect the orphan rule with newtypes
• trait-default-methods — Define traits with required methods and defaulted ones
• trait-dyn-vs-generic — Static vs dynamic dispatch
• trait-object-safety — Keep traits dyn-compatible when needed

12. Conversions (MEDIUM)

• conv-tryfrom-fallible — Implement TryFrom for fallible conversions
• conv-fromstr-parsing — Implement FromStr for string parsing
• conv-asmut-mutable — Accept impl AsMut<T> for mutable borrowed inputs

13. Const & Compile-Time (MEDIUM)

• const-block — Use inline const { } blocks
• const-fn — Make functions const fn
• const-generics — Use const generics
• const-vs-static — const vs static

14. Serde (MEDIUM)

• serde-rename-all — Match naming conventions with #[serde(rename_all = ...)]
• serde-default-compat — Use #[serde(default)] for optional fields
• serde-skip-empty — Omit empty fields with skip_serializing_if
• serde-flatten — Inline nested structs with #[serde(flatten)]
• serde-enum-representation — Choose enum tagging deliberately
• serde-deny-unknown-fields — Reject unexpected keys
• serde-custom-with — Customize (de)serialization
• serde-try-from-validate — Validate while deserializing

15. Pattern Matching (MEDIUM)

• pat-let-else — Use let ... else
• pat-matches-macro — Use matches!()
• pat-if-let-chains — Use if let chains
• pat-exhaustive-enum — Match exhaustively
• pat-at-bindings — Use @ bindings

16. Macros (MEDIUM)

• macro-prefer-functions — Reach for macros only when functions/generics can't express it
• macro-rules-hygiene — Rely on macro_rules! hygiene
• macro-fragment-specifiers — Capture with precise fragment specifiers
• macro-export-crate-path — Export with #[macro_export]
• macro-private-helpers — Hide macro-generated helpers
• macro-proc-two-crate — Use dedicated proc-macro crate
• macro-proc-syn-quote — Build proc macros with syn/quote
• macro-proc-error-spans — Report errors as spanned compile errors

17. Closures (MEDIUM)

• closure-fn-trait-bounds — Require the least restrictive Fn trait
• closure-impl-fn-return — Return closures as impl Fn, not Box<dyn Fn>
• closure-move-capture — Use move for escaping closures
• closure-static-vs-dyn — impl Fn vs dyn Fn
• closure-disjoint-capture — Capture only what you use

18. Collections (MEDIUM)

• coll-binaryheap — Use BinaryHeap for priority queues
• coll-map-choice — Pick the right map (HashMap/BTreeMap/IndexMap)
• coll-seq-choice — Default to Vec; use VecDeque for queue/deque
• coll-set-membership — Use HashSet/BTreeSet for membership tests

19. Naming Conventions (MEDIUM)

• name-types-camel — UpperCamelCase for types and traits
• name-variants-camel — UpperCamelCase for enum variants
• name-funcs-snake — snake_case for functions and variables
• name-consts-screaming — SCREAMING_SNAKE_CASE for constants
• name-lifetime-short — Short lifetime names: 'a, 'b
• name-type-param-single — Single letters for type parameters
• name-as-free — as_ prefix for reference conversions
• name-to-expensive — to_ prefix for expensive conversions
• name-into-ownership — into_ prefix for ownership-consuming conversions
• name-no-get-prefix — Omit get_ prefix for simple getters
• name-is-has-bool — is_/has_ for boolean methods
• name-iter-convention — iter/iter_mut/into_iter
• name-iter-method — Name iterator methods consistently
• name-iter-type-match — Name iterator types after source method
• name-acronym-word — Treat acronyms as words: HttpServer
• name-crate-no-rs — Don't suffix crate names with -rs

20. Testing (MEDIUM)

• test-cfg-test-module — Put unit tests in #[cfg(test)] mod tests { }
• test-use-super — Use use super::*; in test modules
• test-integration-dir — Put integration tests in tests/
• test-descriptive-names — Use descriptive test names
• test-arrange-act-assert — Arrange-Act-Assert structure
• test-proptest-properties — Use proptest for property-based testing
• test-mockall-mocking — Use mockall for trait mocking
• test-mock-traits — Use traits for dependencies
• test-fixture-raii — Use RAII for automatic cleanup
• test-tokio-async — Use #[tokio::test] for async tests
• test-should-panic — Use #[should_panic]
• test-criterion-bench — Use criterion for benchmarking
• test-doctest-examples — Keep doc examples as executable doctests
• test-loom-concurrency — Use loom for concurrent code
• test-snapshot-testing — Use snapshot testing (insta)

21. Documentation (MEDIUM)

• doc-all-public — Document all public items
• doc-module-inner — Use //! for module docs
• doc-examples-section — Include # Examples
• doc-errors-section — Include # Errors
• doc-panics-section — Include # Panics
• doc-safety-section — Include # Safety
• doc-question-mark — Use ? in examples
• doc-hidden-setup — Use # to hide setup
• doc-intra-links — Use intra-doc links
• doc-link-types — Connect related types and functions
• doc-cargo-metadata — Fill Cargo.toml metadata
• doc-crate-readme — Unify README and crate docs

22. Observability (MEDIUM)

• obs-tracing-over-log — Use tracing instead of println!/log
• obs-library-facade — Libraries emit through facades, never install subscribers
• obs-structured-fields — Record structured key-value fields
• obs-instrument-spans — Use #[tracing::instrument]
• obs-levels-filter — Use log levels meaningfully
• obs-error-chain — Log errors with full source chain
• obs-no-sensitive-data — Never log secrets or PII

23. Performance Patterns (MEDIUM)

• perf-iter-over-index — Prefer iterators over manual indexing
• perf-iter-lazy — Keep iterators lazy
• perf-collect-once — Don't collect intermediate iterators
• perf-entry-api — Use entry API for 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
• perf-profile-first — Profile before optimizing
• perf-ahash — Use faster hashers when DoS resistance not needed
• perf-io-buffering — Wrap Read/Write in BufReader/BufWriter

24. Project Structure (LOW)

• proj-lib-main-split — Keep main.rs minimal, logic in lib.rs
• proj-mod-by-feature — Organize 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
• proj-bin-dir — Put multiple binaries in src/bin/
• proj-workspace-large — Use workspaces for large projects
• proj-workspace-deps — Use workspace dependency inheritance
• proj-feature-additive — Design features to be additive
• proj-msrv-declare — Declare MSRV in Cargo.toml
• proj-build-rs-minimal — Keep build.rs minimal

25. Clippy & Linting (LOW)

• lint-deny-correctness — #![deny(clippy::correctness)]
• lint-warn-suspicious — Enable clippy::suspicious
• lint-warn-style — Enable clippy::style
• lint-warn-complexity — Enable clippy::complexity
• lint-warn-perf — Enable clippy::perf
• lint-pedantic-selective — Enable clippy::pedantic selectively
• lint-missing-docs — Warn on missing docs
• lint-unsafe-doc — Require docs for unsafe blocks
• lint-cargo-metadata — Enable clippy::cargo
• lint-rustfmt-check — Run cargo fmt --check in CI
• lint-workspace-lints — Configure lints at workspace level
• lint-cfg-check — Enable unexpected_cfgs
• lint-clippy-nursery-selected — Enable high-value nursery lints selectively

26. Anti-patterns (REFERENCE)

• anti-unwrap-abuse — Don't .unwrap() in production
• 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 points
• 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 recoverable errors
• anti-empty-catch — Don't silently ignore errors
• anti-over-abstraction — Don't over-abstract
• 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 where enums/newtypes provide type safety

---

Rule Application by Task

Task	Primary Categories
New function	own-, err-, name-, pat-
New struct/API	api-, type-, conv-, doc-
Async code	async-, own-
Concurrency / parallelism	conc-, async-, own-
Unsafe code	unsafe-, type-, test-
Error handling	err-, api-, pat-
Type conversions	conv-, api-
Serialization (serde)	serde-, type-, api-
Numeric / arithmetic	num-, type-
Macros / code generation	macro-, anti-
Closures / callbacks	closure-, type-
Logging / observability	obs-, err-
Memory optimization	mem-, own-, perf-
Performance tuning	opt-, mem-, perf-
Code review	anti-, lint-