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/unsafe.md
View on GitHub# Pointers, sharing, concurrency, and unsafe
Prefer references for borrowing and slices for contiguous data. Reach for smart pointers only when their ownership semantics are required.
| Type | Owns heap? | `Send` + `Sync` | Use |
|------|------------|-----------------|-----|
| `&T` | no | if `T: Sync` | shared borrow |
| `&mut T` | no | if `T: Send` (not shared) | exclusive borrow |
| `Box<T>` | yes | if `T: Send` / `Sync` | single-owner heap, recursive types, large values |
| `Rc<T>` | yes | no | single-thread shared ownership |
| `Arc<T>` | yes | if `T: Send + Sync` | multi-thread shared ownership |
| `Cell<T>` | no (wrapper) | not `Sync` | `Copy` interior mutability |
| `RefCell<T>` | no (wrapper) | not `Sync` | runtime borrow checks; MAY panic |
| `Mutex<T>` | no (wrapper) | if `T: Send` | exclusive interior mutability, threads |
| `RwLock<T>` | no (wrapper) | if `T: Send + Sync` | many readers or one writer |
| `OnceCell<T>` | no (wrapper) | not `Sync` | one-time init, one thread |
| `LazyCell<T>` | no (wrapper) | not `Sync` | lazy `OnceCell` |
| `OnceLock<T>` | no (wrapper) | yes | one-time init, threads / `static` |
| `LazyLock<T>` | no (wrapper) | yes | lazy `OnceLock` |
| `*const T` / `*mut T` | n/a | manual | FFI / raw memory; `unsafe` |
Cloning `Rc`/`Arc` may not allocate; the value remains heap-backed and is not strict heapless. Interior mutability changes aliasing and synchronization reasoning.
Docs: [std pointers](https://doc.rust-lang.org/std/), [Nomicon](https://doc.rust-lang.org/nomicon/).
## Shared ownership is not the default
Frequent `Arc<Mutex<T>>` often means unclear ownership. Prefer: a single explicit owner; message passing with bounded queues; immutable shared data; scoped threads borrowing state; partitioned state; IDs or handles into a controlled store.
Use locks when they are the clearest correct design. Lock-free is not automatically faster or safer.
`RefCell` borrow conflicts panic at runtime. Do not use it to hide an ownership problem on a library hot path.
## `Send` and `Sync` are commitments
Do not add unsafe `Send` or `Sync` implementations without a written proof covering all interior state, aliases, callbacks, and FFI. [C-SEND-SYNC](https://rust-lang.github.io/api-guidelines/interoperability.html#c-send-sync): implement them where they are actually true.
## Forbid unsafe by default
```rust
#![forbid(unsafe_code)]
```
in crates that do not require unsafe Rust.
When unsafe is necessary:
- isolate it in the smallest possible module
- expose a safe API
- document every unsafe block with `SAFETY:` covering pointer, alignment, initialization, aliasing, lifetime, and concurrency invariants
- enforce preconditions in release-active code or types
- add focused tests and [Miri](https://github.com/rust-lang/miri) coverage where applicable
- retain a safe reference implementation when optimizing
- NEVER rely solely on `debug_assert!` for safety ([errors.md](errors.md))
## FFI is a complete boundary
FFI docs MUST define: ownership transfer; who allocates and deallocates; allocator compatibility; pointer validity and alignment; buffer length and capacity; lifetime; thread affinity; panic behavior; error representation; callback reentrancy.
Rust panics MUST NOT unwind across an FFI boundary unless the ABI explicitly supports and documents it.
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 |