Skip to content

morganlinton/BeautifulRust / skills/rust-best-practices

rust-best-practices

Unverified

Write idiomatic, robust, maintainable Rust. Use this skill whenever you write, review, refactor, debug, or explain Rust code: new crates, modules, functions, structs, traits, error types, async code, unsafe or FFI code, Cargo.toml, tests, or rustdoc. Trigger on any mention of Rust, cargo, crates, .rs files, the borrow checker, lifetimes, traits, clippy, or rustfmt, even when the user does not ask for "best practices" or "idiomatic" code. Synthesized from the Google Rust Style Guide, the Rust API Guidelines, Effective Rust, Rust Design Patterns, and Microsoft's Pragmatic Rust Guidelines.

FileKindSize
SKILL.mdskill md29.0 KB
evals/bevy-arena-regen/case.yamlconfig783 B
evals/bevy-arena-regen/files/Cargo.lockmanifest32.5 KB
evals/bevy-arena-regen/files/Cargo.tomlmanifest354 B
evals/bevy-arena-regen/files/src/lib.rsscript6.2 KB
evals/bevy-arena-regen/files/tests/arena.rsscript3.3 KB
evals/bevy-arena-regen/graders/01-builds-and-tests-pass.mdmarkdown167 B
evals/bevy-arena-regen/graders/02-regen-tested-headless.mdmarkdown272 B
evals/bevy-arena-regen/graders/03-system-params-by-value.mdmarkdown212 B
evals/bevy-arena-regen/graders/04-keeps-bevy-prelude.mdmarkdown159 B
evals/bevy-arena-regen/graders/05-plain-data-components.mdmarkdown208 B
evals/bevy-arena-regen/graders/06-ordered-after-damage.mdmarkdown334 B
evals/bevy-arena-regen/graders/07-no-panicking-queries.mdmarkdown186 B
evals/bevy-arena-regen/graders/08-clippy-clean.mdmarkdown125 B
evals/bevy-arena-regen/graders/09-health-never-exceeds-max.mdmarkdown134 B
evals/bevy-arena-regen/graders/10-existing-code-not-rewritten.mdmarkdown275 B
evals/bevy-arena-regen/place-files.shexecutablescript62 B
evals/bevy-arena-regen/prompt.mdmarkdown480 B
evals/log-summary-cli/case.yamlconfig581 B
evals/log-summary-cli/graders/01-never-panics-on-bad-input.mdmarkdown212 B
evals/log-summary-cli/graders/02-errors-name-the-file.mdmarkdown104 B
evals/log-summary-cli/graders/03-malformed-lines-counted.mdmarkdown186 B
evals/log-summary-cli/graders/04-paths-as-path-types.mdmarkdown168 B
evals/log-summary-cli/graders/05-sorted-and-skipped-count.mdmarkdown150 B
evals/log-summary-cli/graders/06-dependency-ranges.mdmarkdown134 B
evals/log-summary-cli/graders/07-map-based-counting.mdmarkdown103 B
evals/log-summary-cli/graders/08-aggregation-unit-tested.mdmarkdown147 B
evals/log-summary-cli/prompt.mdmarkdown730 B
evals/refactor-inventory-module/case.yamlconfig677 B
evals/refactor-inventory-module/files/inventory.rsscript3.2 KB
evals/refactor-inventory-module/graders/01-deny-warnings-removed.mdmarkdown90 B
evals/refactor-inventory-module/graders/02-no-rc-refcell-in-api.mdmarkdown141 B
evals/refactor-inventory-module/graders/03-borrowed-param-types.mdmarkdown157 B
evals/refactor-inventory-module/graders/04-error-implements-error.mdmarkdown108 B
evals/refactor-inventory-module/graders/05-no-unwrap-on-fallible-paths.mdmarkdown209 B
evals/refactor-inventory-module/graders/06-getter-renamed.mdmarkdown132 B
evals/refactor-inventory-module/graders/07-bool-param-replaced.mdmarkdown117 B
evals/refactor-inventory-module/graders/08-deterministic-report.mdmarkdown114 B
evals/refactor-inventory-module/graders/09-format-over-concat.mdmarkdown119 B
evals/refactor-inventory-module/graders/10-no-check-then-unwrap.mdmarkdown128 B
evals/refactor-inventory-module/graders/11-changes-listed-with-reasons.mdmarkdown94 B
evals/refactor-inventory-module/graders/12-signature-changes-called-out.mdmarkdown201 B
evals/refactor-inventory-module/place-files.shexecutablescript62 B
evals/refactor-inventory-module/prompt.mdmarkdown507 B
evals/semver-library-api/case.yamlconfig575 B
evals/semver-library-api/graders/01-implements-fromstr.mdmarkdown141 B
evals/semver-library-api/graders/02-implements-display.mdmarkdown94 B
evals/semver-library-api/graders/03-dedicated-error-type.mdmarkdown164 B
evals/semver-library-api/graders/04-common-traits-derived.mdmarkdown127 B
evals/semver-library-api/graders/05-fields-private.mdmarkdown125 B
evals/semver-library-api/graders/06-rustdoc-with-errors-section.mdmarkdown132 B
evals/semver-library-api/graders/07-doc-examples-use-question-mark.mdmarkdown86 B
evals/semver-library-api/graders/08-precedence-rules-tested.mdmarkdown152 B
evals/semver-library-api/graders/09-no-unwrap-in-library-code.mdmarkdown136 B
evals/semver-library-api/graders/10-eq-hash-agree-with-ord.mdmarkdown258 B
evals/semver-library-api/prompt.mdmarkdown667 B
references/bevy.mdmarkdown7.0 KB
references/effective-rust.mdmarkdown13.9 KB
references/google-rust-style-guide.mdmarkdown10.7 KB
references/microsoft-rust-guidelines.mdmarkdown16.2 KB
references/rust-api-guidelines.mdmarkdown11.2 KB
references/rust-design-patterns.mdmarkdown8.2 KB

references/microsoft-rust-guidelines.md

View on GitHub
# Microsoft Pragmatic Rust Guidelines (digest)

Source: https://microsoft.github.io/rust-guidelines/ (version 2026.6, MIT licensed).
Ninety guidelines with `M-` codes, written for teams shipping Rust at scale, with a
chapter aimed at AI coding agents. Read this for error struct design, panic policy,
unsafe policy, async, workspace layout, performance, and what makes code easy for an
agent to work with. "Must" guidelines are hard constraints; "should" allows judgment;
the spirit counts over the letter.

## Universal

- **M-UPSTREAM-GUIDELINES**: follow the Rust API Guidelines, Style Guide, Design
  Patterns, and the UB reference. Especially C-CONV, C-GETTER, C-COMMON-TRAITS, C-CTOR
  (provide `Foo::new()` even with `Default`), C-FEATURE.
- **M-STATIC-VERIFICATION**: compiler lints, clippy, rustfmt, cargo-audit, cargo-hack,
  cargo-udeps, and Miri as check-in gates. Enable `[lints.rust]` such as
  `unsafe_op_in_unsafe_fn` and `missing_debug_implementations`, the clippy groups at
  `priority = -1`, and restriction lints like `undocumented_unsafe_blocks`,
  `allow_attributes_without_reason`, `map_err_ignore`.
- **M-LINT-OVERRIDE-EXPECT**: `#[expect(clippy::x, reason = "...")]` for local
  overrides; an unfulfilled `expect` warns, so stale suppressions are caught. `#[allow]`
  only for generated code and macros.
- **M-PUBLIC-DEBUG**: derive `Debug` on public types. Types holding secrets get a
  hand-written `Debug` (`UserSecret(...)`) plus a unit test asserting the secret never
  appears in output.
- **M-PUBLIC-DISPLAY**: types meant to be read, especially errors and string wrappers,
  implement `Display`. Same redaction rules as `Debug`.
- **M-SMALLER-CRATES**: when in doubt, split into more crates (faster builds, no cycles).
  `web_server`, `web_client`, `web_protocols` rather than one `web` crate with modules.
- **M-WEASEL-WORDS**: no `Service`, `Manager`, `Factory` suffixes. `Bookings` or
  `BookingDispatcher`; `Builder` instead of `Factory`; disposal is `Drop`, not a manager.
  Repeatable instantiation takes `impl Fn() -> Foo`.
- **M-SHORT-NAMES**: at most two short words per identifier. No module name baked into a
  type (`foo::Id`, not `foo::FooId`).
- **M-REGULAR-FN**: associated functions are for instance creation. Computation with no
  receiver is a free function, not `Database::check_parameters(p)`.
- **M-DOCUMENTED-MAGIC**: magic values get a comment on why the value was chosen, the
  effects of changing it, and the external systems involved. Prefer a named `const` with
  a doc comment.
- **M-LOG-STRUCTURED**: structured events with message templates, named
  `<component>.<operation>.<state>`, OpenTelemetry attribute names, PII redacted. Don't
  pre-format with `format!`.

## Libraries: interoperability

- **M-TYPES-SEND**: public types and the futures they produce are `Send`. Assert with
  `const _: () = assert_send::<Foo>();`. An `Rc` held across `.await` makes a future
  `!Send`.
- **M-ESCAPE-HATCHES**: wrappers around native handles provide
  `pub unsafe fn from_native(..)` plus `into_native` / `to_native`, with documented
  safety requirements.
- **M-DONT-LEAK-TYPES**: prefer std types in public APIs. Third-party types only behind a
  feature flag (`serde`) or with substantial benefit.
- **M-FOREIGN-REEXPORTS**: don't `pub use` another crate's items; users depend on it
  directly. Exceptions: umbrella crates, technical splits, hidden macro paths.
- **M-IMPL-ASREF**: parameters may take `impl AsRef<str>` / `AsRef<Path>` /
  `AsRef<[u8]>` when ownership isn't needed. Struct fields hold `String`, `PathBuf`.
- **M-IMPL-RANGEBOUNDS**: accept `impl RangeBounds<T>`, not `(low, high)` pairs, so
  callers write `1..3`, `1..`, `..`.
- **M-IMPL-IO**: write sans-IO functions. Synchronous one-shot I/O takes `impl Read` /
  `impl Write`; runtime-agnostic async takes `futures::io::AsyncRead`.

## Libraries: UX

- **M-SIMPLE-ABSTRACTIONS**: service-level public types don't expose nested type
  parameters. `Service<Backend>` is fine; `Service<Backend<Store>>` is not.
- **M-AVOID-WRAPPERS**: keep `Rc`, `Arc`, `Box`, `RefCell` out of public APIs; use `&T`,
  `&mut T`, `T`. Smart pointers only when fundamental or benchmarked.
- **M-DI-HIERARCHY**: prefer concrete types, then generics over narrow traits, then
  `dyn Trait` wrapped in a custom struct (`DynamicDataAccess(Arc<dyn DataAccess>)`).
  Don't port a C# `IDatabase` into `Rc<dyn Database>`. Test doubles: an enum with a
  `Mock(MockCtrl)` variant.
- **M-ERRORS-CANONICAL-STRUCTS**: errors are situation-specific structs, not one global
  enum. Each holds a `Backtrace`, an optional upstream cause, and helper methods
  (`config_file(&self) -> &Path`). Keep any `ErrorKind` private and expose `is_io()`
  style methods. Capture the backtrace in `new()` or `From`. `Display` prints a summary,
  the backtrace, and the cause. Implement `std::error::Error`. Reuse one general error
  across similar functions (`ParseError` for `parse_json` and `parse_toml`).
- **M-FROM-ERROR**: implement `From<Upstream> for Error` so `?` converts; `map_err`
  only for foreign errors or to add context.
- **M-INIT-BUILDER**: up to two optional parameters use inherent constructors (`new`,
  `with_a`, `with_b`, `with_a_b`). At four or more permutations, `FooBuilder` with
  setters named after fields (`x()`, not `set_x()`), `build()`, and `Foo::builder()`.
  `FooBuilder::new()` is not public. Required parameters arrive through
  `deps: impl Into<FooDeps>`.
- **M-INIT-CASCADED**: constructors with four or more parameters group them into semantic
  types: `Deposit::new(account, amount)`.
- **M-SERVICES-CLONE**: heavyweight services implement cheap `Clone` through
  `Arc<Inner>`; clones share state.
- **M-ESSENTIAL-FN-INHERENT**: core functionality in inherent methods; trait impls
  forward to them, so callers need no import.
- **M-BALANCED-MODULES**: essential items at the crate root; group the rest by use case
  (`account`, `network`), not kind (`traits`, `errors`).
- **M-NO-PRELUDE**: no prelude or `use foo::*` target. Fix the module design instead.
- **M-PARAMETER-CONSISTENCY**: shared parameters in the same order everywhere.
  Call-specific first, ubiquitous (`&logger`) last, closures last, at most one closure.
- **M-COLLECTION-TRAITS**: custom collections provide `Iter`, `IterMut`, `IntoIter`,
  `iter()` / `iter_mut()`, `IntoIterator` for owned and borrowed, `FromIterator`,
  `Extend`, `DoubleEndedIterator` / `ExactSizeIterator` where applicable. `size_hint()`
  is truthful.
- **M-ASYNC-FN**: `async fn foo() -> Result<T, E>` over `fn foo() -> impl Future`. The
  explicit form only in traits or for hot functions (M-ASYNC-STACK-SIZE).

## Libraries: resilience

- **M-AVOID-STATICS**: avoid statics and thread-locals where a consistent value matters.
  Two semver-incompatible copies of a crate get separate statics.
- **M-BUILD-RESULT**: builder setters are infallible; validation, including cross-field
  checks, lives in `build() -> Result<_, _>`.
- **M-INTEGRATION-TESTS**: tests using only the public API go in `tests/`. Prefer an
  integration test whenever either would do.
- **M-LOG-NOT-PRINT**: production code uses the telemetry framework, not `println!` /
  `dbg!`. Only CLIs writing their UI to stdout are exempt.
- **M-MOCKABLE-SYSCALLS**: types doing file, network, clock, entropy, or other
  non-deterministic I/O must be mockable. Provide `new_mocked() -> (Self, MockCtrl)`
  behind `test-util`; don't offer a `Default` that performs I/O.
- **M-NO-GLOB-REEXPORTS**: re-export individually (`pub use foo::{A, B, C};`). Globs
  only for platform HAL modules selected by `cfg(target_os)`.
- **M-STRONG-TYPES**: the strongest std type (`PathBuf` / `Path` for OS data). Plain
  numbers stay plain at API boundaries; no `NonZero` or `Saturating` there.
- **M-STRONG-TYPES-GUARD**: a newtype encoding an invariant (month 1..=12) enforces it in
  a fallible constructor returning `Result`. A panicking `const fn new` is allowed. No
  infallible `From`; use `TryFrom` / `FromStr`.
- **M-TEST-UTIL**: mocks, sensitive-data inspection, safety overrides, and fake data
  generators behind a single `test-util` feature.

## Libraries: building

- **M-OOBE**: non-platform crates build on all Tier 1 targets with only cargo and rustc,
  no extra tools or environment variables. Code generation runs at publish time and its
  output ships in the crate.
- **M-SYS-CRATES**: `-sys` crates build native code from `build.rs` with the `cc` crate,
  embed verifiable upstream sources (URL plus hash), make optional tools optional,
  pre-generate bindgen output, and support static and `libloading` dynamic linking.
- **M-FEATURES-ADDITIVE**: any combination of features compiles. Use a `std` feature,
  never `no-std`. A feature never removes or changes a public item (adding
  `#[non_exhaustive]` enum variants is fine).

## Macros

- **M-MACRO-LAST-RESORT**: macros only when the language can't do the job; they are
  opaque, slow to compile, and brittle across editions.
- **M-EXAMPLE-OVER-PROC**: `macro_rules!` over proc macros when it suffices.
- **M-MACROS-DONT-LIE**: macros never change a type's kind, alter a function signature,
  or add or remove `async`.
- **M-MACRO-MAIN-CRATE**: structure as `foo` (re-exports), `foo_proc` (facade),
  `foo_proc_impl` (logic and tests). Don't support renamed imports.
- **M-MACRO-VERSION-PIN**: companion macro crates pinned with `=x.y.z` and published
  together.
- **M-MACRO-HELPERS**: generated code reaches third-party items through a hidden
  `#[doc(hidden)] pub mod _private { pub use ::bar::Bar; }`.
- **M-PROC-IMPL**: proc macro crate is a thin shim over a normal library crate holding
  the logic and snapshot tests (`insta`); `trybuild` tests for error messages.
- **M-PROC-IMPLIED-ITEMS**: macros don't generate hidden or extra public types (except
  Rocket-style function-plus-struct handlers).

## Applications

- **M-APP-ERROR**: applications and single-app crates may use `anyhow`, `eyre`, or
  similar; libraries follow M-ERRORS-CANONICAL-STRUCTS. Don't mix several app-level
  error types.
- **M-MIMALLOC-APPS**: applications set `#[global_allocator]` to `mimalloc` (up to 25%
  gains reported).
- **M-TARGET-CPU**: server apps compile for the highest `target-cpu` the deployment
  guarantees (`x86-64-v3` via `.cargo/config.toml`). Libraries ignore this.

## FFI

- **M-FFI-NAMING**: `-sys` crates import C libraries; `-ffi` crates export Rust as a
  C-style library.
- **M-FFI-TRANSLATES**: business logic in a safe core crate; the `-ffi` crate only
  translates types and signatures. No `repr(C)` pointer fields in core types.
- **M-ISOLATE-DLL-STATE**: across DLL boundaries share only portable data: `#[repr(C)]`
  types with no statics, thread-locals, `TypeId`, or pointers to non-portable data.

## Correctness

- **M-UNSAFE**: `unsafe` only for a novel abstraction, a benchmarked performance need, or
  FFI/platform calls. Banned: enum casts via `transmute`, `unsafe impl Send` to bypass
  bounds, `transmute` to bypass lifetimes. Each use needs plain-text safety reasoning;
  new abstractions are tested against adversarial code and pass Miri.
- **M-UNSAFE-IMPLIES-UB**: mark a function or trait `unsafe` only when misuse risks
  undefined behavior, not for merely dangerous operations (`delete_database()`).
- **M-UNSOUND**: a safe function that can cause UB through any safe calls is unsound.
  Unsound abstractions are never permissible. If you can't encapsulate it, expose an
  `unsafe fn` and document the contract. Soundness boundaries are module boundaries.
- **M-PANIC-IS-STOP**: panics are not exceptions; a panic means the program should stop
  now. Don't use panics to report errors or rely on them being caught. Valid: programming
  errors (`expect("must never happen")`), const contexts, user-requested unwrap-style
  methods, poisoned-lock `unwrap()`. Code must still be minimally panic-safe.
- **M-PANIC-ON-BUG**: detected bugs and contract violations panic, in libraries and
  applications. Don't return an `Error` the caller can't act on. Fallible input returns
  `Result` (`parse_uri(&str) -> Result<Uri, ParseError>`). Prefer types that make the bad
  state unrepresentable.
- **M-PANIC-CONTINUATION**: `catch_unwind` is a last resort. Libraries don't catch and
  continue. Servers may catch per request but should then promote a controlled restart.
- **M-PANIC-MESSAGE**: every intentional panic (`panic!`, `assert!`, `unreachable!`,
  `todo!`) has a message with the relevant values:
  `assert!(buf.len() >= HEADER_SIZE, "buffer too small: got {} bytes", buf.len())`.

## Performance

- **M-HOTPATH**: decide early whether the crate is performance-relevant; if so, find and
  benchmark hot paths (criterion or divan), profile regularly, document hot spots.
- **M-THROUGHPUT**: optimize for items per CPU cycle; batched APIs; no hot spinning or
  per-item work where batching is possible.
- **M-YIELD-POINTS**: long CPU-bound async work yields (`yield_now().await`) roughly
  every 10 to 100 microseconds.
- **M-MEM-REUSE**: let callers own and reuse buffers: `get_in(id, &mut value)` alongside
  a convenience `get(id)`; provide `clear()`. Arenas for deep call stacks.
- **M-LOG-OVERHEAD**: no telemetry in hot inner loops; no per-event `format!`.
- **M-AVOID-INDIRECTION**: don't stack `Arc` layers on hot types; lift hot cacheable
  fields (`enabled: bool`) into the owning struct.
- **M-BOX-DST**: frequently created, immutable, non-user-visible sequences use
  `Box<[T]>`, `Box<str>`, or `Arc<str>` instead of `Vec` / `String`.
- **M-SHRINK-TO-FIT**: `shrink_to_fit()` on long-lived growable collections built
  without a reservation.
- **M-FAST-HASHER**: `foldhash` or `FxHash` for trusted internal keys; the default hasher
  for untrusted input.
- **M-INITIAL-CAPACITY**: `with_capacity` when the size is known; `collect()` over push
  loops.
- **M-ASYNC-STACK-SIZE**: track the size of hot futures with `size_of_val` in a test;
  shrink state held across `.await`; move setup outside the async block.

## Project

- **M-CARGO-WORKSPACE**: share metadata, versions, and lints through
  `[workspace.dependencies]` and `[workspace.lints]`, with `default-features = false`
  on workspace dependency definitions.
- **M-CRATES-FLAT-FOLDER**: one workspace `Cargo.toml`, crates as siblings under
  `crates/`, never nested inside another crate or its `src/`.
- **M-CRATES-IN-WORKSPACE**: every crate is a workspace member; siblings referenced as
  `sibling.workspace = true`.
- **M-LATEST-EDITION**: new crates use the latest stable edition (2024 or later).
- **M-MSRV**: set a minimum supported Rust version at creation; raise it conservatively
  in minor releases.

## Documentation

- **M-CANONICAL-DOCS**: public items get a one-line summary, extended docs, then
  `# Examples`, `# Errors`, `# Panics`, `# Safety` (required for `unsafe fn`), `# Abort`
  as applicable. Parameters described in prose, not a table.
- **M-DOC-INLINE**: `#[doc(inline)]` on `pub use` of crate-internal items; not for std or
  third-party types.
- **M-FIRST-DOC-SENTENCE**: first sentence on one line, about 15 words; it becomes the
  module summary.
- **M-MODULE-DOCS**: every public module has `//!` docs: what it contains, when to use
  it, examples, observable side effects.

## AI (agent-specific)

- **M-DESIGN-FOR-AI**: what makes an API easy for humans makes it easy for agents:
  idiomatic design, thorough docs on every module and public item, directly usable
  examples, strong types, APIs testable through fakes or mocks, good coverage of
  observable behavior. The compiler's checks counterbalance an agent's limited
  understanding.
- **M-NO-META-DESIGN-DOCUMENTATION**: no design journals, "why we picked X" essays, or
  agent self-report tables (a `Rule | Applied | Where` list) in crate or module docs.
  Document the end state. A README section on enduring architectural goals is fine.
- **M-RUST-SHAPED**: when porting from C#, Java, or C++, don't translate constructs
  one-to-one. Keep the domain logic; use Rust idioms for errors, tasks, ownership, and
  traits. A `throw_if_null()` signals a problem.
- **M-SINGLE-ITEM-PATH**: one path per public item. Don't combine
  `pub mod db { pub struct Connection; }` with `pub use db::Connection;`. Agents tend to
  add re-exports during refactors instead of redesigning. A `pub(crate) mod` with a
  single `pub use` is fine.
- **M-TAUTOLOGICAL-TESTS**: don't write tests that restate constants or mirror
  implementation branches (`assert_eq!(CHECKPOINTS, [0, 90, 180, 270])`). Test
  properties: even spacing, monotonicity, round-trips.
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