Skip to content

massimodeluisa/rust-best-practices-skill / skills/rust-best-practices

rust-best-practices

Verified

Write 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

FileKindSize
SKILL.mdskill md6.0 KB
evals/evals.jsonconfig3.2 KB
references/allocation.mdmarkdown10.2 KB
references/design.mdmarkdown7.9 KB
references/errors.mdmarkdown6.8 KB
references/official.mdmarkdown8.1 KB
references/ownership.mdmarkdown3.9 KB
references/performance.mdmarkdown3.1 KB
references/quality.mdmarkdown10.9 KB
references/review.mdmarkdown4.4 KB
references/unsafe.mdmarkdown3.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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall