kromatv/kroma / .claude/skills/rust-best-practices
rust-best-practices
VerifiedRust best practices. Use when reading or editing any .rs file, designing a crate's public API, choosing an error type, splitting a workspace, or writing async code on tokio. Triggers - "rust best practices", "is this idiomatic", "should this be a newtype", "anyhow or thiserror", "why does the borrow checker", "review this Rust".
Rust best practices
One idea underneath every rule: a wrong program should not compile. Where a
project also writes TypeScript, the same table lives one language over in
typescript-best-practices. Rust hands you more of that for free, so the
failures move: unwrap(), a clone() that silences the borrow checker, a
stringly typed API, a blocking call on the async runtime.
| Rule | Summary |
|---|---|
| Enums with data | Model variants as an enum carrying each variant's payload. A struct of Option fields plus a bool admits states that cannot happen. |
| Newtypes | Wrap primitives that mean something: struct UserId(Uuid), struct Seconds(u32). Two String parameters in a row swap silently; two newtypes do not. |
| Parse at the edge | Untrusted bytes become a typed value once, at the boundary, with serde plus validation. Inside, trust the type. Bound the body before parsing. |
| Errors by layer | A library returns its own enum error (thiserror), a binary composes with anyhow. Never Box<dyn Error> in a public signature you own. |
| No unwrap in library code | ? propagates, let ... else returns early. expect only for an invariant, with a message naming what was violated. Tests and main may panic. |
| Context, not stringly errors | Add context as you propagate (.context("reading manifest")), keep the source chain. Formatting an error into a String early throws the cause away. |
| Borrow in, own out | Take &str, &[T], impl IntoIterator. Return the owned type. A clone() added to end a borrow argument is a design smell; restructure the scope. |
| Deliberate visibility | pub(crate) by default. pub is an API promise. #[non_exhaustive] on a public enum or struct that will grow. |
| Conversions via traits | From/TryFrom rather than to_thing() helpers, so ? and generic code pick them up. |
| Don't block the runtime | No file, SQLite, or CPU work on an async thread: spawn_blocking. Never hold a std::sync::Mutex guard across .await. |
| Cancellation safety | Anything inside select! may be dropped at any await point. Long work takes a cancellation token and honours it. |
| Iterators over index loops | Express the transformation. Avoid collect() into a Vec you immediately iterate. |
| SAFETY on unsafe | Every unsafe block carries a // SAFETY: comment stating the invariant that makes it sound. No exceptions. |
| Secrets never in Debug | A type holding a token, key or password gets a hand-written Debug that redacts. Derived Debug leaks into every log line. |
| Clippy is the floor | cargo clippy --workspace --all-targets clean, warnings denied in CI. A lint you disagree with is suppressed at the line, with the reason. |
| Real tests | Unit tests beside the code, integration tests in tests/. No sleep for synchronisation. Property tests where the invariant is stateable. |
Examples: references/patterns.md.
Read the project's Cargo.toml lints table and its clippy configuration before
deciding a rule here does not apply.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |