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