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/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.
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