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/performance.md
View on GitHub# Performance
Do not optimize on intuition. Establish: a representative workload; release-mode measurements; hardware and compiler metadata; latency distribution (not only averages); throughput; peak memory; allocation counts; bytes processed; cache behavior when relevant; regression thresholds.
Always measure with `--release`. Dev profiles are not production.
## Algorithms and layout first
1. Asymptotic behavior
2. Bounded candidate sets
3. Avoid unnecessary work
4. Contiguous data layout
5. Reduce bytes read and written
6. Avoid allocation and copies
7. Cache locality
8. Branch predictability
9. Vectorization or arch-specific kernels only after the above
Fewer arithmetic ops is not a speedup if memory traffic, cache misses, or synchronization dominate.
## Clones and copies
Find with review and profiling: clones inside loops; large structs passed by value; repeated string/byte conversions; serialize-then-immediately-deserialize; intermediate `collect`; copies across abstraction boundaries.
Do not remove a clone if that makes ownership unsound or materially harms clarity. Fix the ownership model rather than introducing fragile references.
Clippy: `redundant_clone`, `needless_collect`, `clone_on_copy`. `cargo clippy -- -D clippy::perf`.
## Reuse prepared state
For allocation-free steady state: validate and prepare once; precompute immutable tables; allocate permitted capacity at init; reuse worker-local scratch; reset lengths and cursors rather than reconstructing containers; keep repeated operations free of lazy init.
## Inspect generated code selectively
Assembly or LLVM IR for critical kernels, to verify: bounds-check elimination, vectorization, unexpected calls, hidden allocation, integer ops, branch structure, arch-specific instructions. Complements tests; does not replace them.
`#[inline]` only when a benchmark proves it. The compiler already inlines well.
Keep small `Copy` types on the stack. Avoid passing huge types by value. Heap-allocate recursive structures (`Box` around children). Large `const` arrays: do not materialize them on the stack then box; build a boxed slice without a giant stack temporary. Spill-capable small-vectors are forbidden on strict / allocation-free paths unless spilling is structurally impossible.
## Tooling
- [`cargo bench`](https://doc.rust-lang.org/cargo/commands/cargo-bench.html) for microbenchmarks. Treat a stable >5% win as interesting, not automatic merge.
- [`cargo flamegraph`](https://github.com/flamegraph-rs/flamegraph) (`cargo install flamegraph`). Always profile `--release`. Width is time on CPU; color is meaningless. On macOS, [samply](https://github.com/mstange/samply) is often a better DX.
- Benchmarks used as merge gates MUST have stable fixtures, known warmup, hardware metadata, noise-aware thresholds, allocation counters where relevant, separate correctness tests, and recorded baseline changes. Do not make fragile microbenchmark noise a correctness gate.
Keep a dedicated optimized test lane with `debug-assertions = true` ([errors.md](errors.md), [quality.md](quality.md)). Normal release benchmarks reflect production settings.
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 |