rust-best-practice

Rust Best Practice — Master Reference

This skill is an exhaustive, book-grade reference for writing, reviewing, and reasoning about production-quality Rust. It exists to make every piece of Rust code Claude touches — no matter how small — idiomatic, sound, performant, and maintainable by default.

How to use this skill

1. Always consult this file first whenever Rust is involved, even for a two-line snippet. Do not skip straight to writing code.
2. Identify the task type using the table below, then read the matching reference file(s) in references/ before writing or reviewing code. Reference files are self-contained "book chapters" — each has its own table of contents, code examples, rationale, anti-patterns, and a Real References section with authoritative URLs (The Rust Book, Rust Reference, Rust API Guidelines, RFCs, Clippy lint docs, official crate docs).
3. For code review: read the relevant reference(s), then check the user's code against the checklists at the end of each file. Report violations grouped by severity (soundness/correctness > API design > style/idiom > performance/micro-optimization), citing the specific guideline (e.g. "C-GETTER" from the Rust API Guidelines, or a specific Clippy lint name).
4. For writing new code: read the relevant reference(s) first, then write code that satisfies every applicable checklist item. Prefer standard library and well-established crates (see references/13-security-and-supply-chain.md for vetting criteria) over reinventing functionality.
5. Cite sources: when explaining why a practice matters, point to the specific guideline/RFC/lint referenced in the file, and give the user the real URL — don't invent or paraphrase from memory alone.
6. Multiple reference files often apply to one task (e.g. writing an async web handler touches error handling, async, and API design) — read all that are relevant, not just one.

Task → Reference file map

Core philosophy (applies everywhere)

• Make invalid states unrepresentable. Prefer encoding invariants in the type system over runtime checks (newtypes, enums, the typestate pattern) — see 01 and 04.
• Parse, don't validate. Convert unstructured input into structured types at the boundary; the rest of the program works with types that are already known-valid.
• Explicit over implicit. No silent truncation, no hidden panics, no surprising allocations. Prefer TryFrom over lossy as casts, checked_*/saturating_* arithmetic over raw operators where overflow matters.
• Errors are values, panics are bugs. Reserve panic!/unwrap()/expect() for genuine programmer errors or truly unrecoverable states; propagate everything else as Result.
• Zero-cost abstraction is a goal, not an excuse. Write clear code first; reach for unsafe or manual optimization only with a measured bottleneck and a documented safety argument.
• Lint at maximum strictness. Every new project should enable clippy::all, clippy::pedantic (selectively), and #![deny(unsafe_op_in_unsafe_fn)] in unsafe-heavy crates — see 09.

Quick anti-pattern smell test (use during any review)

Flag these immediately regardless of which reference file is primary:

• .unwrap()/.expect() on Result/Option in library or production code paths (not tests/prototypes)
• unsafe blocks without a // SAFETY: comment explaining the invariant upheld
• .clone() used to silence a borrow-checker error without understanding why it was needed
• Stringly-typed errors (Result) instead of a proper error enum
• #[allow(warnings)] or blanket #[allow(clippy::all)]
• Public structs with all-pub fields where invariants should be enforced by constructors
• Blocking calls (std::thread::sleep, sync file I/O, std::sync::Mutex held across .await) inside async functions
• Manual impl Drop fighting the borrow checker instead of RAII guard types
• Box in library public APIs (fine in application main.rs, not in reusable crates)

Always ground recommendations in the cited real-world sources inside each reference file rather than general impressions — link the user to the primary source when explaining a rule.