---

name: rust-idioms description: Rust refactoring and idiomatic patterns guidelines from the Rust Community (formerly rust-refactor). This skill should be used when writing, reviewing, or refactoring Rust code to ensure idiomatic patterns and clean architecture. Triggers on tasks involving Rust types, ownership, error handling, traits, modules, conversions, or iterator patterns.

Rust Community Rust Refactoring Best Practices

Comprehensive refactoring and idiomatic patterns guide for Rust applications, maintained by the Rust Community. Contains 44 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Rust code with strong type guarantees
• Refactoring ownership and borrowing patterns
• Designing error handling strategies
• Creating public APIs with traits and generics
• Organizing modules and controlling visibility

Rule Categories by Priority

Quick Reference

1. Type Safety & Newtype Patterns (CRITICAL)

• type-newtype-units - Use newtype pattern for unit safety
• type-newtype-invariants - Encode invariants in newtype constructors
• type-non-exhaustive-enums - Use non-exhaustive for extensible enums
• type-phantom-data - Use PhantomData for type-level state
• type-strong-typing-strings - Replace stringly-typed APIs with strong types
• type-builder-required-fields - Use typestate builders for required fields

2. Ownership & Borrowing (CRITICAL)

• own-prefer-borrowing - Prefer borrowing over ownership in parameters
• own-cow-conditional-clone - Use Cow for conditional ownership
• own-accept-borrowed-types - Accept borrowed types over owned references
• own-return-owned-for-flexibility - Return owned types for caller flexibility
• own-avoid-unnecessary-clone - Avoid unnecessary clone calls
• own-lifetime-elision - Leverage lifetime elision rules

3. Error Handling Patterns (HIGH)

• err-use-result-not-panic - Use Result instead of panic! for recoverable errors
• err-thiserror-for-libraries - Use thiserror for library error types
• err-anyhow-for-applications - Use anyhow for application error handling
• err-question-mark-propagation - Use the question mark operator for error propagation
• err-option-for-absence - Use Option for absence, not sentinel values

4. API Design & Traits (HIGH)

• api-derive-common-traits - Derive common traits for public types
• api-impl-standard-traits - Implement standard traits for ergonomic APIs
• api-generic-bounds - Use trait bounds for generic flexibility
• api-sealed-traits - Use sealed traits to prevent external implementation
• api-builder-pattern - Use builder pattern for complex construction
• api-extension-traits - Use extension traits to add methods to foreign types

5. Module & Visibility (MEDIUM-HIGH)

• mod-minimize-pub-api - Minimize public API surface
• mod-pub-use-reexports - Use pub use for clean module re-exports
• mod-split-large-modules - Split large modules into submodules
• mod-crate-prefix-imports - Use crate:: prefix for internal imports
• mod-tests-submodule - Use tests submodule for unit tests

6. Conversion Traits (MEDIUM)

• conv-impl-from-not-into - Implement From instead of Into
• conv-asref-for-flexibility - Accept AsRef for flexible string parameters
• conv-impl-deref-for-newtypes - Implement Deref for transparent newtype access
• conv-tryfrom-for-fallible - Use TryFrom for fallible conversions
• conv-inner-function-pattern - Use inner function pattern to reduce monomorphization

7. Idiomatic Patterns (MEDIUM)

• idiom-default-trait - Implement Default instead of new() without arguments
• idiom-constructor-naming - Follow constructor naming conventions
• idiom-let-else - Use let-else for early returns on pattern match failure
• idiom-struct-update-syntax - Use struct update syntax for partial overrides
• idiom-destructuring-assignment - Use destructuring for multiple returns and field access
• idiom-match-guards - Use match guards for complex conditions

8. Iterator & Collections (LOW-MEDIUM)

• iter-prefer-iterators-over-loops - Prefer iterator methods over manual loops
• iter-use-collect-turbofish - Use turbofish for explicit collect type
• iter-filter-map-combined - Use filter_map for combined filter and transform
• iter-avoid-collect-then-iterate - Avoid collecting then iterating
• iter-enumerate-for-indices - Use enumerate instead of manual index tracking

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Full Compiled Document

For a single-file comprehensive guide, see AGENTS.md.