# Rust Refactor

> Rust Refactor Best Practices

- Skill: `comeonoliver/rust-refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/rust-refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/rust-refactor/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/comeonoliver/rust-refactor

---

# Rust Refactor Best Practices

Architectural refactoring guide for Rust applications. Contains 91 rules across 10 categories, prioritized by impact from critical (type safety, ownership) to incremental (iterator idioms).

## When to Apply

- Refactoring existing Rust codebases or planning large-scale restructuring
- Reviewing PRs for architectural issues and code smells
- Designing type-safe APIs with proper error handling
- Organizing Rust project structure with Cargo workspaces
- Improving module boundaries and visibility control
- Applying consistent naming conventions (RFC 430)
- Replacing stringly-typed APIs with strong types

## Rule Categories

| Category | Impact | Rules | Key Topics |
|----------|--------|-------|------------|
| Type Safety & Patterns | CRITICAL | 20 | Newtypes, typestate builders, PhantomData, enums, trait objects, associated types |
| Ownership & Borrowing | CRITICAL | 6 | Borrowing, Cow, lifetime elision, clone avoidance |
| Error Handling | HIGH | 15 | thiserror/anyhow, two-tier strategy, context, graceful degradation |
| API Design & Traits | HIGH | 6 | Sealed traits, extension traits, generic bounds, builder pattern |
| Project Organization | HIGH | 6 | Cargo workspaces, crate separation, feature grouping |
| Module & Visibility | MEDIUM-HIGH | 9 | Re-exports, visibility control, test co-location, module splitting |
| Naming Conventions | MEDIUM-HIGH | 13 | RFC 430, snake_case, PascalCase, predicates, unit suffixes |
| Conversion Traits | MEDIUM | 5 | From/Into, AsRef, TryFrom, Deref |
| Idiomatic Patterns | MEDIUM | 6 | Default, let-else, destructuring, match guards |
| Iterator & Collections | LOW-MEDIUM | 5 | Iterator methods, collect turbofish, filter_map |

## Quick Reference

**Critical patterns** — get these right first:
- Use newtype patterns to prevent unit confusion and encode invariants
- Prefer borrowing over ownership in function parameters
- Use thiserror for library errors, anyhow for application errors
- Use typestate builders for compile-time required field enforcement

**Common mistakes** — avoid these anti-patterns:
- Stringly-typed APIs instead of strong types
- Unnecessary clone calls when borrowing would work
- panic! for recoverable errors instead of Result
- Over-exposing internal types with pub visibility

## Table of Contents

1. [Type Safety & Patterns](references/_sections.md#1-type-safety--patterns) — **CRITICAL**
   - 1.1 [Encode Invariants in Newtype Constructors](references/type-newtype-invariants.md) — CRITICAL
   - 1.2 [Use Newtype Pattern for Unit Safety](references/type-newtype-units.md) — CRITICAL
   - 1.3 [Replace Stringly-Typed APIs with Strong Types](references/type-strong-typing-strings.md) — CRITICAL
   - 1.4 [Use Non-Exhaustive for Extensible Enums](references/type-non-exhaustive-enums.md) — CRITICAL
   - 1.5 [Use PhantomData for Type-Level State](references/type-phantom-data.md) — CRITICAL
   - 1.6 [Use Typestate Builders for Required Fields](references/type-builder-required-fields.md) — CRITICAL
   - 1.7 [Use Associated Types for Related Type Relationships](references/type-associated-types.md) — HIGH
   - 1.8 [Use Enums for Type-Safe Variants](references/type-enum-variants.md) — HIGH
   - 1.9 [Use Option<T> for Nullable Fields](references/type-option-nullable-fields.md) — HIGH
   - 1.10 [Use async_trait for Async Trait Methods](references/type-async-trait.md) — MEDIUM
   - 1.11 [Use bitflags! for Type-Safe Bit Flags](references/type-bitflags.md) — MEDIUM
   - 1.12 [Use Box<dyn Trait> for Runtime Polymorphism](references/type-boxed-trait-objects.md) — MEDIUM
   - 1.13 [Use Builder Pattern with Method Chaining](references/type-builder-pattern.md) — MEDIUM
   - 1.14 [Derive Copy for Simple Enums](references/type-enum-copy-simple.md) — MEDIUM
   - 1.15 [Implement Operator Traits for Domain Types](references/type-operator-overload.md) — MEDIUM
   - 1.16 [Use PhantomData for Unused Generic Parameters](references/type-phantom-unused-params.md) — MEDIUM
   - 1.17 [Use Public Fields for Data Structs](references/type-public-fields.md) — MEDIUM
   - 1.18 [Use Consistent Derive Order for Data Structs](references/type-standard-derives.md) — MEDIUM
   - 1.19 [Group Related Trait Implementations Together](references/type-trait-impl-grouping.md) — LOW
   - 1.20 [Use Type Aliases for Complex Generics](references/type-type-aliases.md) — LOW
2. [Ownership & Borrowing](references/_sections.md#2-ownership--borrowing) — **CRITICAL**
   - 2.1 [Accept Borrowed Types Over Owned References](references/own-accept-borrowed-types.md) — CRITICAL
   - 2.2 [Avoid Unnecessary Clone Calls](references/own-avoid-unnecessary-clone.md) — CRITICAL
   - 2.3 [Use Cow for Conditional Ownership](references/own-cow-conditional-clone.md) — CRITICAL
   - 2.4 [Leverage Lifetime Elision Rules](references/own-lifetime-elision.md) — CRITICAL
   - 2.5 [Prefer Borrowing Over Ownership in Function Parameters](references/own-prefer-borrowing.md) — CRITICAL
   - 2.6 [Return Owned Types for Caller Flexibility](references/own-return-owned-for-flexibility.md) — CRITICAL
3. [Error Handling](references/_sections.md#3-error-handling) — **HIGH**
   - 3.1 [Use Two-Tier Error Strategy](references/err-two-tier-strategy.md) — HIGH
   - 3.2 [Use thiserror for Custom Error Types](references/err-thiserror-enum.md) — HIGH
   - 3.3 [Use anyhow for Application Error Handling](references/err-anyhow-for-applications.md) — HIGH
   - 3.4 [Use Result Instead of panic! for Recoverable Errors](references/err-use-result-not-panic.md) — HIGH
   - 3.5 [Reserve panic! for Unrecoverable Situations](references/err-panic-unrecoverable.md) — HIGH
   - 3.6 [Include Path Context in IO Errors](references/err-path-context.md) — HIGH
   - 3.7 [Use Option for Absence, Not Sentinel Values](references/err-option-for-absence.md) — HIGH
   - 3.8 [Use the Question Mark Operator for Error Propagation](references/err-question-mark-propagation.md) — HIGH
   - 3.9 [Use context() and with_context() for Error Messages](references/err-anyhow-context.md) — MEDIUM
   - 3.10 [Use bail! for Validation Failures](references/err-bail-validation.md) — MEDIUM
   - 3.11 [Use Graceful Degradation for Non-Critical Operations](references/err-graceful-degradation.md) — MEDIUM
   - 3.12 [Use #[source] for Error Chaining](references/err-source-attribute.md) — MEDIUM
   - 3.13 [Use expect() with Descriptive Messages](references/err-expect-message.md) — LOW
   - 3.14 [Use ok_or_else for Expensive Error Construction](references/err-ok-or-else.md) — LOW
   - 3.15 [Define Module-Local Result Type Alias](references/err-result-alias.md) — LOW
4. [API Design & Traits](references/_sections.md#4-api-design--traits) — **HIGH**
   - 4.1 [Derive Common Traits for Public Types](references/api-derive-common-traits.md) — HIGH
   - 4.2 [Implement Standard Traits for Ergonomic APIs](references/api-impl-standard-traits.md) — HIGH
   - 4.3 [Use Trait Bounds for Generic Flexibility](references/api-generic-bounds.md) — HIGH
   - 4.4 [Use Sealed Traits to Prevent External Implementation](references/api-sealed-traits.md) — HIGH
   - 4.5 [Use Builder Pattern for Complex Construction](references/api-builder-pattern.md) — HIGH
   - 4.6 [Use Extension Traits to Add Methods to Foreign Types](references/api-extension-traits.md) — HIGH
5. [Project Organization](references/_sections.md#5-project-organization) — **HIGH**
   - 5.1 [Use Cargo Workspace for Multi-Crate Projects](references/org-cargo-workspace.md) — HIGH
   - 5.2 [Use snake_case for All Directory Names](references/org-directory-naming.md) — HIGH
   - 5.3 [Separate Binary and Library Crates](references/org-binary-library-separation.md) — HIGH
   - 5.4 [Group Crates by Feature Domain](references/org-feature-domain-grouping.md) — MEDIUM
   - 5.5 [Use Dedicated Common Crate for Shared Utilities](references/org-common-crate.md) — MEDIUM
   - 5.6 [Keep Crate Structure Flat](references/org-flat-crate-structure.md) — MEDIUM
6. [Module & Visibility](references/_sections.md#6-module--visibility) — **MEDIUM-HIGH**
   - 6.1 [Use Explicit Module Declarations in lib.rs](references/mod-explicit-declarations.md) — HIGH
   - 6.2 [Co-locate Tests as test.rs Files](references/mod-colocated-tests.md) — HIGH
   - 6.3 [Minimize Public API Surface](references/mod-minimize-pub-api.md) — MEDIUM-HIGH
   - 6.4 [Use pub use for Clean Module Re-exports](references/mod-pub-use-reexports.md) — MEDIUM-HIGH
   - 6.5 [Split Large Modules into Submodules](references/mod-split-large-modules.md) — MEDIUM-HIGH
   - 6.6 [Use crate Prefix for Internal Imports](references/mod-crate-prefix-imports.md) — MEDIUM-HIGH
   - 6.7 [Use tests Submodule for Unit Tests](references/mod-tests-submodule.md) — MEDIUM-HIGH
   - 6.8 [Use cfg Attributes for Conditional Modules](references/mod-conditional-compilation.md) — MEDIUM
   - 6.9 [Separate Types and Errors into Dedicated Files](references/mod-types-errors-files.md) — MEDIUM
7. [Naming Conventions](references/_sections.md#7-naming-conventions) — **MEDIUM-HIGH**
   - 7.1 [Use snake_case for Functions and Methods](references/name-function-snake-case.md) — HIGH
   - 7.2 [Use PascalCase for Types](references/name-type-pascal-case.md) — HIGH
   - 7.3 [Use snake_case for Module Names](references/name-module-snake-case.md) — HIGH
   - 7.4 [Use new for Constructors](references/name-constructor-new.md) — HIGH
   - 7.5 [Use SCREAMING_SNAKE_CASE for Constants](references/name-constant-screaming.md) — MEDIUM
   - 7.6 [Prefix Getter Functions with get_](references/name-getter-prefix.md) — MEDIUM
   - 7.7 [Use is_, has_, should_ for Boolean Predicates](references/name-boolean-predicates.md) — MEDIUM
   - 7.8 [Use to_ and from_ for Conversions](references/name-conversion-to-from.md) — MEDIUM
   - 7.9 [Use Descriptive Suffixes for Type Specialization](references/name-type-suffixes.md) — MEDIUM
   - 7.10 [Include Unit Suffixes in Field Names](references/name-field-unit-suffixes.md) — LOW
   - 7.11 [Use Descriptive or Single-Letter Generic Parameters](references/name-generic-parameters.md) — LOW
   - 7.12 [Use Single Lowercase Letters for Lifetimes](references/name-lifetime-parameters.md) — LOW
   - 7.13 [Name Test Files as test.rs](references/name-test-files.md) — LOW
8. [Conversion Traits](references/_sections.md#8-conversion-traits) — **MEDIUM**
   - 8.1 [Implement From Instead of Into](references/conv-impl-from-not-into.md) — MEDIUM
   - 8.2 [Accept AsRef for Flexible String Parameters](references/conv-asref-for-flexibility.md) — MEDIUM
   - 8.3 [Implement Deref for Transparent Newtype Access](references/conv-impl-deref-for-newtypes.md) — MEDIUM
   - 8.4 [Use TryFrom for Fallible Conversions](references/conv-tryfrom-for-fallible.md) — MEDIUM
   - 8.5 [Use Inner Function Pattern to Reduce Monomorphization](references/conv-inner-function-pattern.md) — MEDIUM
9. [Idiomatic Patterns](references/_sections.md#9-idiomatic-patterns) — **MEDIUM**
   - 9.1 [Implement Default Instead of new() Without Arguments](references/idiom-default-trait.md) — MEDIUM
   - 9.2 [Follow Constructor Naming Conventions](references/idiom-constructor-naming.md) — MEDIUM
   - 9.3 [Use let-else for Early Returns on Pattern Match Failure](references/idiom-let-else.md) — MEDIUM
   - 9.4 [Use Struct Update Syntax for Partial Overrides](references/idiom-struct-update-syntax.md) — MEDIUM
   - 9.5 [Use Destructuring for Multiple Returns and Field Access](references/idiom-destructuring-assignment.md) — MEDIUM
   - 9.6 [Use Match Guards for Complex Conditions](references/idiom-match-guards.md) — MEDIUM
10. [Iterator & Collections](references/_sections.md#10-iterator--collections) — **LOW-MEDIUM**
    - 10.1 [Prefer Iterator Methods Over Manual Loops](references/iter-prefer-iterators-over-loops.md) — LOW-MEDIUM
    - 10.2 [Use Turbofish for Explicit collect Type](references/iter-use-collect-turbofish.md) — LOW-MEDIUM
    - 10.3 [Use filter_map for Combined Filter and Transform](references/iter-filter-map-combined.md) — LOW-MEDIUM
    - 10.4 [Avoid Collecting Then Iterating](references/iter-avoid-collect-then-iterate.md) — LOW-MEDIUM
    - 10.5 [Use enumerate Instead of Manual Index Tracking](references/iter-enumerate-for-indices.md) — LOW-MEDIUM

## References

1. [https://rust-lang.github.io/api-guidelines/](https://rust-lang.github.io/api-guidelines/)
2. [https://rust-unofficial.github.io/patterns/](https://rust-unofficial.github.io/patterns/)
3. [https://doc.rust-lang.org/book/](https://doc.rust-lang.org/book/)
4. [https://www.lurklurk.org/effective-rust/](https://www.lurklurk.org/effective-rust/)
5. [https://rust-lang.github.io/rust-clippy/](https://rust-lang.github.io/rust-clippy/)

## Related Skills

- For performance optimization, see `rust-optimise` skill