Guidelines
Use page descriptions to select pages before loading them. After loading a conditional page, apply it only when its Activation section matches.
Foundations
- House style and Rust philosophy - load for overall code shape, OO-leaning defaults, and Rust idiom tradeoffs.
- Library vs application conventions - load before choosing policies that differ for libraries, apps, CLIs, tests, or services.
- Rust edition and MSRV - load when setting edition,
rust-version, stable/nightly posture, or checking MSRV impact.
Tooling and Project Shape
- rustfmt and formatting - load when configuring rustfmt or handling formatting exceptions.
- rustc and Clippy lints - load when configuring lints, fixing Clippy, or justifying lint exceptions.
- Cargo, workspaces, features, and dependencies - load for workspace layout, features, dependency choices, and MSRV-aware dependency changes.
- Application workspace architecture - load when deciding application crate boundaries, dependency direction, component and adapter roles, or composition roots.
- Modules, visibility, and re-exports - load when changing
mod,pub, facades, re-exports, or canonical public paths. - Naming, imports, and prelude policy - load for item names, acronym casing, imports, globs, and preludes.
- Documentation and rustdoc examples - load when writing rustdoc, public docs, examples, or
Errors/Panics/Safetysections.
Type and API Design
- Struct design and encapsulation - load when designing structs, fields, invariants, receivers, or encapsulation boundaries.
- Constructors and builders - load when choosing
new,try_new,Default, builders, or typestate builders. - Newtype pattern and semantic wrappers - load when adding IDs, units, validated strings, value objects, or orphan-rule wrappers.
- Enums vs traits vs generics vs trait objects - load when choosing closed sets, open extension, static dispatch, or runtime heterogeneity.
- Trait design - load when designing traits, bounds, associated types, blanket impls, sealed traits, or object-safe APIs.
- Deriving and common trait implementations - load when adding derives or manual impls for standard traits.
- Conversions, getters, and method naming - load for
From,TryFrom,AsRef,Deref, accessors, andas_/to_/into_names. - Typestate and state machines - load for ordered workflow states, data-bearing enums,
PhantomData, or compile-time transitions. - Public API evolution - load for externally consumed APIs, semver, deprecation,
#[non_exhaustive], or#[must_use].
Ownership and Data Flow
- Ownership, borrowing, and clone policy - load when choosing borrowed inputs, owned outputs,
String/&str,Pathparameters,IntoIterator,AsRef,Cow, accessors, snapshots, or clone tradeoffs. - Lifetimes - load when explicit lifetimes, borrowed structs, or lifetime-heavy APIs appear.
- Smart pointers and interior mutability - load when choosing
Box,Rc,Cell,RefCell,Weak, or one-time initialization. - Collections and data structures - load when choosing
Vec, maps, sets, deterministic ordering, capacity, or specialized collection crates.
Errors, Safety, and Diagnostics
- Error taxonomy and layer boundaries - load when defining domain, infrastructure, boundary, or branch-oriented error layers.
- Library errors vs application errors - load before choosing
thiserror,anyhow,miette, or public error stability. - Error propagation, context, and messages - load when adding
?, context, source chains, or error message text. - Panics, unwrap, expect, and assertions - load when using panic,
unwrap,expect, assertions,unreachable!,todo!, or public panic docs. - Validation and invariants - load when parsing inputs, enforcing constructors, encoding invariants, or re-checking stale state.
- Logging and observability - load when adding
tracing, spans, fields, levels, error logs, or redaction.
Async and Concurrency
- Async runtime and when to use async - load when deciding sync vs async posture, Tokio use, or runtime boundaries.
- Async API design and task lifecycle - load when adding async APIs, async traits, spawning, task owners,
Send, or shutdown handles. - Cancellation, shutdown, and blocking work - load for cancellation tokens,
select!, timeouts,spawn_blocking, CPU work, or graceful shutdown. - Concurrency primitives - load when adding channels, locks, atomics,
Arcshared state, or coordination primitives.
Everyday Implementation
- Control flow - load when choosing
match,if let,let else, guards, early returns, mutable locals, or in-place updates. - Option and Result idioms - load when transforming
Option/Result, usingok_or_else,transpose,map, or explicit branching. - Iterators, closures, and loops - load when choosing iterator chains, loops, closure capture,
collect,fold, ortry_fold.
Testing and Release
- Testing and doctests - load when writing unit tests, integration tests, doctests, fixtures, or test helpers.
- Property tests, snapshots, benchmarks, and CI - load when configuring test commands, snapshots, property tests, benchmarks, or CI gates.
- Unsafe code and macros - load when touching
unsafe, FFI, raw pointers,macro_rules!, proc macros, or generated APIs.