Rust

---
name: rust
description: "Enforces default Rust coding standards for agents writing or refactoring Rust: ownership, error handling, types, testing, async, and API design. Use before editing Rust unless the repo provides stricter local rules."
version: "1.0.0"
category: development
triggers: rust, cargo, clippy, rustfmt, tokio, async rust, lifetime, borrow checker
---

# Rust

Default coding standards for Rust. **Repo conventions and configured tooling take precedence** — if `Cargo.toml`, `clippy.toml`, `CLAUDE.md`, or project rules specify stricter or different standards, follow those instead.

---

## Tooling

Run the repo's configured lint, format, and test commands before finishing. If none are configured, use:

- **Format**: `cargo fmt --check` (fix with `cargo fmt`)
- **Lint**: `cargo clippy -- -D warnings`
- **Tests**: `cargo test` targeting changed crates, not the full workspace
- **Bench**: `cargo bench` if performance-sensitive code changed

Don't suppress clippy lints with `#[allow(...)]` without a documented reason.

## Ownership & Borrowing

- Prefer borrowing (`&T`, `&mut T`) over cloning — clone only when ownership transfer is genuinely needed
- Accept `&str` not `&String`, `&[T]` not `&Vec<T>`, `&Path` not `&PathBuf` in function parameters
- Use `Cow<'_, str>` when a function sometimes allocates and sometimes does not
- Keep lifetimes simple — if you need more than two named lifetime parameters, restructure
- Never `.clone()` to silence the borrow checker without understanding why it complains

For patterns and examples: `get_skill_file(name="rust", path="references/ownership.md")`

## Error Handling

- Libraries: define error enums with `thiserror`. Applications: use `anyhow` with `.context()`
- Propagate with `?` — avoid manual `match` on `Result` just to re-wrap
- No `.unwrap()` outside tests and cases with a proof comment explaining why it cannot fail
- Use `Option` for absence, `Result` for failure — do not conflate them
- Convert foreign errors at crate boundaries with `From` impls

For error type patterns: `get_skill_file(name="rust", path="references/error-handling.md")`

## Type System

- Use enums to make invalid states unrepresentable — not structs with optional fields
- Newtype pattern for domain concepts (`struct UserId(u64)`) to prevent type confusion
- Prefer generics + trait bounds over `dyn Trait` unless you need runtime polymorphism
- Derive `Debug` on everything. Add `Clone`, `PartialEq`, `Eq`, `Hash` where appropriate
- Do not introduce `Box<dyn Any>` — find the concrete type or use an enum

For type modeling patterns: `get_skill_file(name="rust", path="references/types.md")`

## Testing

- Unit tests in `#[cfg(test)] mod tests` in the same file
- Integration tests in `tests/` directory, one file per major feature
- Use `-> Result<()>` for tests with fallible operations instead of `.unwrap()` chains
- Property-based testing with `proptest` for parsing, serialization, or algorithmic code
- Mock external I/O with trait objects or generics — not heavy mock frameworks

For testing patterns: `get_skill_file(name="rust", path="references/testing.md")`

## Async

- Use tokio as the default runtime unless the project specifies otherwise
- CPU-bound work goes in `spawn_blocking`, never in async tasks
- All async I/O must have explicit timeouts (`tokio::time::timeout`)
- Understand `Send + Sync` bounds — do not sprinkle them to silence the compiler
- Use `tokio::select!` with cancellation safety awareness

For async patterns: `get_skill_file(name="rust", path="references/async.md")`

## Performance

- **Profile before optimizing** — use `cargo flamegraph` or `criterion` benchmarks
- Prefer iterator chains over indexed loops — they compile to the same machine code
- Pre-allocate with `Vec::with_capacity` when size is known or estimable
- Avoid unnecessary allocations: `&str` over `String`, `&[T]` over `Vec<T>` in read paths

For profiling tools and optimization patterns: `get_skill_file(name="rust", path="references/performance.md")`

## API & Design

- Implement `Display` for user-facing types, `Debug` for all types
- Use builder pattern for structs with more than 3-4 optional fields
- Implement `From`, not `Into` — you get `Into` for free
- Accept generics at boundaries: `impl AsRef<Path>`, `impl Into<String>`
- Unsafe: isolate in minimal blocks, document invariants with `// SAFETY:` comments, prefer safe abstractions from established crates (`bytemuck`, `zerocopy`, `crossbeam`)

## Before You Finish

If you touched Rust: verify `cargo fmt`, `cargo clippy`, and targeted `cargo test` pass before closing your work.