Rust Guardrails

These guardrails apply to all Rust code you write, review, or modify. They exist because LLM-generated Rust tends to repeat the same classes of mistakes: lazy unwrap() calls, unnecessary cloning, overly broad visibility, and sloppy dependency management. Following these rules produces code that compiles cleanly, passes clippy, and looks like it was written by someone who actually ships Rust in production.

Error Handling

Rust's error handling is one of its greatest strengths — but only when used properly. The ? operator exists so you don't have to write boilerplate match arms, and crates like thiserror and anyhow exist so you don't have to hand-roll Display and Error impls.

• Never use `unwrap()` or `expect()` in production code. These are fine in tests and examples where a panic is acceptable, but in library or application code they're a ticking time bomb. Use ? to propagate, or handle the error explicitly.
• Always define structured error types with `thiserror` first. Every module that can fail should have its own error enum with #[derive(Debug, Error)] and #[error(...)] variants. This gives callers something to pattern-match on and produces clear error messages. thiserror is the right choice for both libraries and applications — the distinction is about where anyhow fits in, not whether to define error types.
• Use `anyhow` only at the application boundary — in main(), CLI entry points, or top-level orchestration where you're collecting errors from multiple subsystems and just need to report them. anyhow::Result wraps your thiserror types; it never replaces them. If you find yourself writing anyhow::Result on an internal function, stop and define a proper error type instead.
• Propagate errors with `?` — don't write match result { Ok(v) => v, Err(e) => return Err(e) } when result? does the same thing.
• Add context with `.context()` / `.with_context()` from anyhow at the boundary, or use map_err to convert between your thiserror types deeper in the stack.

Ownership & Borrowing

Unnecessary cloning is the most common sign of "fighting the borrow checker" — it compiles, but it's wasteful and hides design problems. Think about whether a function actually needs to own data before taking it by value.

• No unnecessary `clone()` — if you clone, add a comment explaining why (e.g., // clone needed: value used after move into spawned task).
• Prefer `&T` over owned `T` in function parameters unless the function genuinely needs ownership (e.g., storing the value in a struct, moving it into a thread).
• Use `Cow<'_, str>` when a function might or might not need to allocate — this avoids forcing the caller to allocate when they already have a &str.
• Prefer `&str` over `String` in function parameters. If the caller has a String, they can pass &s; the reverse isn't free.
• Prefer `impl Iterator` or `impl IntoIterator` over `Vec` in function parameters — this lets callers pass any iterator without collecting first.

Visibility

Rust defaults to private for good reason. Every pub item is a commitment — it's part of your API surface and can't be removed without a breaking change.

• Minimum visibility by default — use pub(crate) instead of pub unless the item is genuinely part of the public API. Leave items private when they don't need to be accessed outside their module.
• `#[must_use]` on all functions returning Result or Option — a silently ignored error is a bug waiting to happen.
• `#[non_exhaustive]` on public enums and structs that might grow — this lets you add variants or fields without breaking downstream code.

Patterns

• Edition 2021 minimum — there's no reason to target older editions in new code.
• `#[derive(Debug)]` on all types — everything should be debuggable. Add Clone, PartialEq, Eq, Hash etc. when semantically appropriate.
• Prefer exhaustive `match` over wildcard _ — when you enumerate all variants explicitly, the compiler tells you when a new variant is added. Use _ only when the set is truly open-ended or when matching on values like integers/strings.
• Use `if let` / `let else` over match for single-variant checks — if let Some(x) = val { ... } is cleaner than a full match with a _ => {} arm.
• Use `HashMap::entry()` for insert-or-get patterns — never write if !map.contains_key(&k) { map.insert(k, v); } when map.entry(k).or_insert_with(|| v) does the same thing in one lookup instead of two. The Entry API is also the right tool for counters (*entry.or_insert(0) += 1), default values, and conditional insertion. It's more efficient and signals intent clearly.
• Builder pattern for structs with more than 3 fields — constructors with many positional arguments are error-prone and hard to read.
• Prefer `impl Trait` over `dyn Trait` when the concrete type is known at compile time — monomorphization gives better performance and the code is often simpler.

Dependencies

Bad dependency choices haunt a project for years. A few minutes of due diligence saves a lot of pain.

• Prefer well-maintained, widely-used crates: serde, tokio, tracing, clap, thiserror, anyhow. These have large userbases, good docs, and responsive maintainers.
• No yanked or deprecated crates — check before adding a dependency.
• Pin major versions in Cargo.toml — write tokio = "1" not tokio = "*". Wildcard versions invite breakage.
• Use `smol-toml` for TOML parsing unless you need to preserve formatting/comments during editing (in which case toml_edit is appropriate). Avoid the toml crate — smol-toml is lighter and faster.
• Disable default features and enable only what's needed — e.g., tokio = { version = "1", default-features = false, features = ["rt-multi-thread", "macros"] }. This keeps compile times and binary size down.

Formatting & Style

• `cargo fmt` compliant — never fight rustfmt. If a formatting choice feels wrong, it's still better than inconsistency across the codebase.
• `cargo clippy` clean — no #[allow(clippy::...)] unless you have a genuine reason, documented with a comment explaining why the lint doesn't apply.
• Doc comments (`///`) on all public items — types, functions, methods, constants. Explain what it does and when to use it, not how it works internally.
• Module-level doc comment (`//!`) in lib.rs — this becomes the crate-level documentation.

Unsafe

Rust's safety guarantees are its core value proposition. unsafe should be a last resort, not a convenience.

• No `unsafe` unless absolutely necessary — and "the safe version is slightly slower" is almost never a valid reason.
• Every `unsafe` block must have a `// SAFETY:` comment explaining the invariant that makes this safe. This isn't optional — it's how you prove to reviewers (and your future self) that the code is sound.

Testing

• `#[cfg(test)]` module in the same file for unit tests — keep tests close to the code they test.
• Integration tests in `tests/` directory — these test public API behavior from the outside.
• Use `assert_eq!` / `assert_ne!` over assert!(x == y) — the former gives you the actual vs. expected values on failure, which makes debugging far easier.
• Test error cases, not just the happy path — if a function returns Result, write tests that verify the error variants too.