Rust

Rust

Lean on the type system and the borrow checker. They are the design surface, not an obstacle. When the compiler rejects code, the ownership model is wrong — restructure who owns and who borrows rather than reaching for .clone(), Rc, or unsafe to silence it. Make illegal states unrepresentable: encode invariants in types so the wrong code fails to compile instead of failing at runtime. A fight with the borrow checker is a design review the compiler is giving you for free.

Route to Reference

Read the reference before doing focused work in its area; SKILL.md alone is sufficient for routine code.

• Idioms and ownership patterns — ${CLAUDE_SKILL_DIR}/references/idioms.md borrowing/ownership restructuring,

impl Trait vs generics vs dyn, iterator adapters, match/if let/let else, newtype and builder patterns, From/Into/TryFrom, the as_/to_/into_ cost cheat-table

• Error handling — ${CLAUDE_SKILL_DIR}/references/errors.md Result/Option/?, thiserror enum templates,

anyhow .context(), the panic/unwrap/expect policy, error-type design (Display/Error/Send/Sync)

• Anti-patterns — ${CLAUDE_SKILL_DIR}/references/anti-patterns.md AI-produced anti-patterns mapped to the Clippy

lints that catch them, with the idiomatic fix for each

• API design — ${CLAUDE_SKILL_DIR}/references/api-guidelines.md the Rust API Guidelines C-* checklist, RFC 430

naming, #[non_exhaustive], #[must_use], common-trait derives, sealed traits, builders

• Parallelism — ${CLAUDE_SKILL_DIR}/references/parallelism.md threads, scoped threads, rayon, Send/Sync,

channels, shared state (Arc/Mutex) — the CPU-bound multicore path

• Async — ${CLAUDE_SKILL_DIR}/references/async.md the Future/executor model, Tokio, the compiler-invisible

footgun checklist (blocking in async, holding !Send across .await), "do you even need async?"

• Project structure — ${CLAUDE_SKILL_DIR}/references/structure.md mod.rs-free layout, cargo workspaces, the

[lints]/[workspace.lints] table, profiles, features, MSRV

• Toolchain — ${CLAUDE_SKILL_DIR}/references/toolchain.md the fmt/clippy/nextest/deny verification gates,

rust-analyzer configuration, recommended compiler and Clippy lint sets

• Edition 2024 — ${CLAUDE_SKILL_DIR}/references/edition-2024.md Rust 2024 edition specifics and migration via

cargo fix --edition

• Documentation — ${CLAUDE_SKILL_DIR}/references/documentation.md rustdoc conventions, doctests, missing_docs,

intra-doc links, semver-checks

Naming

• Casing follows RFC 430: UpperCamelCase for types/traits/enum variants, snake_case for functions/methods/modules,

SCREAMING_SNAKE_CASE for consts/statics.

• Acronyms are one word in UpperCamelCase (Uuid, Stdin, not UUID, StdIn); lower-cased in snake_case.
• Getters omit the get_ prefix: fn first(&self) -> &First, not fn get_first. Use get only when one obvious value

is gotten (e.g. Cell::get).

• Ad-hoc conversion methods signal cost through their prefix: as_ = free borrow-to-borrow view; to_ = expensive

(allocates or computes); into_ = consuming, ownership transfer.

• Collection iterators are iter (&T), iter_mut (&mut T), into_iter (T); the iterator type name matches the

method (into_iter -> IntoIter).

• Names use consistent verb-object word order (ParseAddrError, matching ParseIntError). Drop weasel words —

Manager, Service, Factory, Helper, Util rarely belong in a type name; name the thing for what it is (Bookings, not BookingService), append a quality only when it does something specific (BookingDispatcher).

• A Builder is Rust's name for a factory. Accept impl Fn() -> Foo rather than a FooBuilder parameter.

Ownership and Borrowing

• Accept the least-owning type that does the job: &str over &String, &[T] over &Vec, &T over T when not

consuming. Return owned values; borrow in parameters.

• Treat .clone() as a signal, not a fix. A clone to satisfy the borrow checker usually means lifetimes or ownership

are structured wrong — split the borrow, narrow the scope, or restructure who owns the data.

• Reach for Rc/Arc only for genuine shared ownership (a graph, a cache, a value with no single owner), not to dodge

a lifetime annotation.

• Prefer adjusting a function to take &self/&T over cloning at the call site. Borrow at the narrowest scope so a

mutable borrow ends before the next access begins (non-lexical lifetimes allow this).

• Use lifetime elision wherever it applies; write explicit lifetimes only when the compiler asks or when they document a

real relationship between inputs and outputs.

Error Handling

• Functions that can fail return Result; absence-not-error returns Option. Propagate with ?, do not

match-and-rewrap.

• Libraries define typed errors with thiserror (one enum, #[error("...")] per variant, #[from] for source

conversions). Applications use anyhow::Result and attach .context(...) at each layer.

• Error types implement std::error::Error, Display, Debug, and are Send + Sync + 'static so they cross threads

and compose with anyhow/Box.

• .unwrap() and .expect() are permitted only on a provable invariant (with .expect("why this cannot fail")

documenting the proof), inside const contexts, or in tests. They are never error-propagation.

• A detected programming bug panics; it is not an Error. A panic means "stop the program" — never use panics to

communicate recoverable errors upstream, and never assume a panic will be caught. Genuinely fallible operations (parsing, I/O, user input) return Result.

• Prefer making invalid states uncompilable over validating at runtime: a NonEmptyVec or a parsed Email newtype

beats a runtime check on a raw Vec/String.

Traits and Generics

• Static dispatch is the default: generics (fn f) or impl Trait in argument and return position.

Monomorphization keeps it allocation-free and inlinable.

• Use dyn Trait only for genuine runtime polymorphism — heterogeneous collections (Vec>), plugin

boundaries, or breaking deep monomorphization. Always write dyn explicitly (Box, &dyn Handler); bare-trait-object syntax has been an error since edition 2021.

• impl Trait in argument position is shorthand for an anonymous generic; in return position it hides a concrete type.

Switch to a named generic when the caller must name the type or supply it via turbofish.

• Derive the common traits eagerly where they fit: Debug on every public type, plus Clone, Copy, PartialEq,

Eq, Hash, PartialOrd, Ord, Default as semantics allow. Implement Display for types meant to be read by humans (errors, string-like wrappers).

• Implement conversions via the standard traits — From (which gives Into free), TryFrom, AsRef, AsMut — not

ad-hoc methods, so generic code and ? interoperate.

Iterators and Pattern Matching

• Express transformations as iterator adapter chains (.iter().filter().map().collect()), not manual index loops. They

are bounds-check-friendly, lazy, and clearer.

• Reach for for x in &collection over for i in 0..collection.len(); index only when the index itself is the data.
• match arms must be exhaustive — let the compiler enforce that every variant is handled rather than ending with a

catch-all _ that silently swallows new variants.

• Use if let / while let for single-pattern matches, and let ... else { return / continue / bail } to bind-or-

bail in one line instead of nesting the happy path inside a match.

• Destructure in the pattern (function params, let, match arms) rather than reaching into fields by .0/.field

afterward.

Concurrency: Choose the Right Model First

Pick the concurrency model from the workload before writing any concurrent code — this decision is not interchangeable:

• CPU-bound / multicore compute (parsing, hashing, image processing, number crunching) -> OS threads or rayon

(par_iter). Never reach for async here — async provides zero parallel speedup for CPU work; it only interleaves tasks at .await points on (often) a single logical flow.

• Many concurrent I/O operations (thousands of sockets, requests, file handles) -> async / Tokio. Async wins by

not blocking a thread while waiting on I/O, letting one runtime juggle huge numbers of in-flight operations.

• A handful of blocking I/O tasks -> plain threads are simpler than dragging in an async runtime; use async only

when the concurrency count makes a thread-per-task model wasteful.

Further rules once the model is chosen:

• Shared state crosses threads via Arc> / Arc>; immutable shared data via Arc. Move work and

ownership across threads with channels (std::sync::mpsc, crossbeam, or tokio::sync in async).

• Public types should be Send (and usually Sync) so they work under Tokio and behind runtime abstractions. A !Send

value held across an .await makes the whole future !Send — keep Rc/RefCell out of async scopes that span an await.

• Never block in async: no std::thread::sleep, no synchronous file/network I/O, no long CPU loops on the runtime.

Offload CPU work with tokio::task::spawn_blocking or a rayon pool, and use the runtime's async timers/IO.

• The borrow checker does not see deadlocks or blocking-in-async — those footguns are invisible at compile time. Read

references/async.md before writing async code.

Project Structure

• Use the mod.rs-free layout: a module foo lives in foo.rs, its submodules in foo/bar.rs. Never create new

mod.rs files.

• Set all lint levels in the [lints] (or [workspace.lints]) table in Cargo.toml, not in scattered #![deny(...)]

attributes or RUSTFLAGS. This keeps lint policy in one auditable place and inherited across the workspace.

• Override a project-global lint at a narrow scope with #[expect(lint, reason = "...")], not #[allow] — expect

warns when the lint stops firing, preventing stale overrides. (#[allow] is acceptable on generated code/macros.)

• Multi-crate projects use a cargo workspace with a shared [workspace.lints] and [workspace.dependencies]. Split a

crate when a submodule is independently useful — many small crates compile faster and prevent dependency cycles.

• Keep unsafe confined to the smallest possible module; soundness boundaries are module boundaries. Every unsafe

block carries a // SAFETY: comment justifying it. Never write sound-looking safe wrappers over unsound assumptions.

Toolchain Gates

Code is not done until these pass (run via Bash, surfacing each command):

• cargo fmt --check — formatting is non-negotiable; never hand-format.
• cargo clippy --all-targets --all-features -- -D warnings — Clippy clean across the whole build graph, warnings as

errors. Fix the cause; suppress a lint only with a scoped #[expect(..., reason = "...")].

• cargo nextest run and cargo test --doc — nextest is the fast test runner but does not execute doctests, so

the separate --doc run is mandatory to keep documentation examples honest.

• cargo deny check (or cargo audit) — gate dependencies for advisories, license, and source policy.

Doc Comments

• //! documents the crate root and modules; /// documents items (functions, types, fields, variants). Write docs as

part of the change, not after.

• Use the standard rustdoc sections: # Examples, # Panics (when the fn can panic), # Errors (what a Result

returns on failure), # Safety (the invariants a caller of an unsafe fn must uphold).

• Doctests use ? for fallible calls (wrap the body so it returns Result), never .unwrap() — examples are also

documentation of idiomatic usage.

• Libraries enable #![warn(missing_docs)] so every public item is documented. Link related items with intra-doc links

([Type], [mod::func]).

• When you change an exported symbol's signature or behavior, update its doc comment in the same edit — a stale doc is

worse than none.

Code Navigation (LSP Required)

A rust-analyzer LSP is configured for .rs files. For semantic navigation, use LSP tools — they understand types, traits, and macro expansion in ways text search cannot:

• goToDefinition — jump to where a symbol is defined (through re-exports and macros).
• findReferences — every real use of a symbol, not textual name collisions.
• hover — resolved type, signature, and docs at a position.
• workspaceSymbol — locate a type/fn/trait by name across the workspace.
• goToImplementation — concrete implementors of a trait, or the trait a method satisfies.
• incomingCalls / outgoingCalls — call hierarchy for impact analysis before a change.

Use Grep/Glob only for non-semantic text: comments, string literals, config files, log messages, Cargo.toml entries. Reaching for Grep to find a definition or all callers is a mistake when the LSP resolves it precisely.

Integration

• the-coder owns the language-agnostic workflow — discovery, planning, verification loop. This skill governs

Rust-specific conventions only; defer the workflow mechanics to the-coder and apply these rules within it.

• rust-testing owns the test ecosystem (#[test]/integration/doctest layout, cargo-nextest, proptest, insta,

criterion, mockall, rstest). When writing or reviewing tests, that skill leads; it relies on this skill for general language conventions and on references/async.md for async-test mechanics.

• When this skill's conventions conflict with an established pattern already pervasive in the codebase, the codebase

wins — follow it and flag the divergence once.

Application

When writing Rust:

• Apply every convention above silently — do not narrate "per RFC 430 I'll name this...". Just write idiomatic code.
• Match the surrounding codebase. If it diverges from these conventions consistently (e.g. uses mod.rs, a different

error crate), follow the codebase and note the divergence once rather than fighting it file-by-file.

• Run the toolchain gates before declaring the work done.

When reviewing Rust:

• Cite the specific violation (file:line and the rule), then show the corrected code inline. Do not lecture in the

abstract.

• Prioritize correctness and soundness (unsound unsafe, blocking-in-async, panics-as-errors, data races) over style

nits; let cargo fmt and Clippy carry the mechanical issues.

• Confirm the concurrency model fits the workload (CPU-bound vs I/O-bound) before reviewing the concurrency details.

---

The borrow checker is a collaborator, not an adversary. When it pushes back, the answer is almost never .clone(), Rc, or unsafe — it is a clearer ownership structure. Encode invariants in types so wrong code does not compile, keep unsafe rare and justified, and let the toolchain gates (fmt, clippy, nextest + doctests, deny) be the final word on done.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xobotyi
• Source: xobotyi/cc-foundry
• License: MIT

Install and usage instructions live in the source repository linked above.