UtakataKyosui / rust-coding-skill

Skill Content

---
name: rust-coding-skill
description: Guides Claude in writing idiomatic, efficient, well-structured Rust code using proper data modeling, traits, impl organization, macros, and build-speed best practices.
---

# Rust Coding Skill

## Instructions
1. Fully understand the user request:  
   Determine whether the task involves designing data structures, implementing traits, writing macros, modeling domain logic, or organizing modules.  
   Identify key constraints such as mutability needs, ownership flow, async context, interior mutability, or concurrency boundaries.

2. Plan data structures with precision:  
   - Choose between `struct`, `enum`, or `newtype` based on domain needs.  
   - Consider ownership of each field:  
     - Use `&str` vs `String`, slices vs vectors, `Arc<T>` when sharing, or `Cow<'a, T>` for flexible ownership.  
   - Model invariants explicitly using types (e.g., `NonZeroU32`, `Duration`, custom enums).  
   - Prefer `enum` for state machines instead of boolean flags or loosely related fields.

3. Write idiomatic Rust implementations:  
   - Place `impl` blocks immediately below the struct/enum they modify.  
   - Group related methods together: constructors, getters, mutation methods, domain logic, helpers.  
   - Provide clear constructors (`new`, `with_capacity`, builders) where appropriate.  
   - Use trait implementations (`Display`, `Debug`, `From`, `Into`, `TryFrom`) to simplify conversions.  
   - Prefer returning `Result<T, E>` instead of panicking.  
   - Keep functions short to help lifetime inference and clarity.

4. Apply rigorous documentation and code-style best practices:  
   - Use `///` doc comments for structs, enums, fields, and methods.  
   - Use `//!` for module-level documentation when explaining design or architecture.  
   - Include examples in docs where valuable.  
   - Run `cargo fmt` and `cargo clippy --all-targets --all-features` to maintain consistency.  
   - Reserve blank lines between logically separate methods and sections.

5. Use macros effectively but responsibly:  
   - Apply `derive` macros (`Debug`, `Clone`, `Serialize`, `Deserialize`, etc.) to reduce boilerplate.  
   - Create small, focused declarative macros to eliminate repetitive patterns.  
   - For procedural macros, enforce clear boundaries and predictable generated code.

6. Optimize build speed when relevant:  
   - On Linux, configure `.cargo/config.toml` to use the `mold` linker when appropriate.  
   - Use `sccache` to cache compiled artifacts during development.  
   - Minimize unnecessary dependencies and feature flags.  
   - Prefer `cargo check` during rapid iteration over `cargo build`.  
   - Split crates into lightweight workspaces to avoid monolithic rebuilds.  
   - Use `cargo profile` settings for tuned dev/release defaults.

7. Encourage maintainable module and project structure:  
   - Organize code into modules reflecting ownership and domain boundaries.  
   - Use `pub(crate)` instead of `pub` when possible; expose only what needs exposing.  
   - Keep APIs small and expressive; avoid leaking internal types.  
   - Use meaningful file and module names aligned with functionality.

8. Provide explanations and alternatives:  
   For every code design, explain why a certain pattern is chosen and propose alternatives when relevant, such as:  
   - builder pattern vs simple constructor  
   - enum-based state machine vs multiple booleans  
   - shared ownership via `Arc<T>` vs message passing channels  
   - slice-based APIs for performance vs owned collections for convenience  
   - deriving traits vs manual implementations for custom logic

9. Maintain clarity, safety, and idiomatic style at all times:  
   Prioritize predictable ownership flow, correct lifetimes, and ergonomic APIs that reflect common Rust patterns.