massimodeluisa/rust-best-practices-skill / skills/rust-best-practices
rust-best-practices
VerifiedWrite and review production Rust using the official API Guidelines, Style Guide, and this engineering standard: allocation contracts, ownership, Result vs panic, debug_assert, Clippy, tests, rustdoc, unsafe, and Cargo CI. Use when writing, reviewing, or refactoring Rust; choosing borrow vs clone; designing crate APIs; handling errors; bounding heap use; configuring clippy or rustfmt; or when the user runs /rust-best-practices. Do not use for other languages. Triggers: rust, rustc, cargo, clippy, rustfmt, ownership, clone, borrow, Result, unwrap, expect, panic, thiserror, anyhow, heapless, no_std, allocation, debug_assert, type-state, Send, Sync, unsafe, FFI, rustdoc, MSRV, rust-best-practices, rust style, rust guidelines
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| evals/evals.json | config | 3.2 KB |
| references/allocation.md | markdown | 10.2 KB |
| references/design.md | markdown | 7.9 KB |
| references/errors.md | markdown | 6.8 KB |
| references/official.md | markdown | 8.1 KB |
| references/ownership.md | markdown | 3.9 KB |
| references/performance.md | markdown | 3.1 KB |
| references/quality.md | markdown | 10.9 KB |
| references/review.md | markdown | 4.4 KB |
| references/unsafe.md | markdown | 3.3 KB |
references/review.md
View on GitHub# Review checklist and anti-patterns
Use this on `/rust-best-practices <path>` and on every Rust change. Quote the line, name the rule, give the fix.
## Correctness and API
- Invalid states represented with types, not conventions?
- Caller-controlled failures returned as typed errors?
- Integer and range calculations checked before indexing?
- Panic conditions rare and documented under `# Panics`?
- Ownership transfer intentional and visible (`into_` / `to_` / `as_`)?
- Public fields and types actually required?
- Official [checklist](https://rust-lang.github.io/api-guidelines/checklist.html) `C-*` ids that apply?
## Allocation and bounds
- Memory profile declared (strict heapless / allocation-free steady state / allocation-conscious)?
- Hot or repeated operations avoid heap allocation and reallocation?
- Inputs borrowed; outputs or scratch caller-owned where the profile requires it?
- All capacities finite and documented?
- Exhaustion returns an explicit error without spilling to the heap?
- Hidden paths through formatting, telemetry, async, traits, callbacks, FFI, and dependencies reviewed?
- Large buffers kept off limited thread stacks?
## `debug_assert!`
- Each assertion a real internal invariant?
- Already established by types or release-active checks?
- Release behavior still correct if the assertion is removed?
- Free of required side effects?
- Independent of unsafe-code soundness?
- Condition and message avoid owned allocation?
## Performance and determinism
- Optimization supported by measurement (`--release`)?
- Data layout contiguous and cache-conscious where relevant?
- Unnecessary clones, copies, and intermediate collections avoided?
- Canonical output independent of thread scheduling and unordered containers?
- Optimized implementation has a reference oracle and equivalence tests?
## Safety and concurrency
- Unsafe forbidden or tightly isolated with `SAFETY:`?
- FFI ownership and allocator rules explicit?
- Queues, workers, retries, and temporary storage bounded?
- Shared ownership used intentionally, not as an escape hatch?
## Tests and documentation
- Success, capacity, malformed-input, and error paths tested?
- Allocation behavior tested after initialization?
- Optimized tests run with debug assertions enabled?
- Public APIs document allocation, errors, panics, bounds, and determinism?
- TODOs linked to issues?
- Examples compile as doc tests where practical?
## Anti-patterns
Avoid unless a documented exception explains why they are correct:
- cloning to silence the borrow checker
- accepting `String` or `Vec<T>` when only a borrow is needed
- returning a `Vec<T>` from every query or parser (especially under a heapless or allocation-free profile)
- `unwrap()` / `expect()` for external input
- `debug_assert!` as validation or a safety precondition
- state changes inside debug assertions
- `format!()` in a strict runtime error path
- preallocating a `Vec` and calling the subsystem "heapless"
- a small-vector type that may spill to the heap on a strict path
- hiding allocations behind logging or error context
- boxing futures or traits in a hot path without measuring or documenting it
- unbounded channels, retries, recursion, or task creation
- assigning canonical IDs based on thread completion order
- replacing clear code with an abstraction that obscures bounds and memory access
- writing unsafe before proving safe code is insufficient
- disabling lints globally to accommodate one call site
- claiming allocation freedom from source inspection or one benchmark input alone
- implementing both `Copy` and `Iterator` on one type
- wildcard imports in production modules
- TODOs with no issue, owner, or removal condition
- comments that restate the next line
## Preferred shape
Production Rust should be easy to reason about under success and failure:
- explicit domain types
- borrowed inputs
- caller-owned or fixed-capacity output and scratch where the profile requires it
- bounded execution
- typed, allocation-free core errors
- release-active validation of external input
- `debug_assert!` for internal invariants already established by correct code
- no unsafe by default
- deterministic output where artifacts or proofs depend on it
- measurement-backed optimization
- tests that verify allocation behavior and boundary conditions
- rich application adapters separated from a lean runtime core
A zero-allocation claim is a contract. Treat it with the same rigor as memory safety, wire-format compatibility, and deterministic output.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |