If you've ever asked Claude Code, Cursor, or Copilot to "add a function" to a Rust crate, you know the output: borrowed &str everywhere with explicit lifetimes leaking into public signatures, .unwrap() on every Result, a std::sync::Mutex held across an .await, and a panic!() instead of an error path. It compiles. It also looks like C++ wearing a Rust hat.

The cause is the training data. Most Rust code AI has seen is example snippets — the parts that elide error handling, ignore async correctness, and use unwrap() because brevity beats robustness in a blog post. Production Rust looks nothing like this.

Drop a CLAUDE.md at the crate root and the AI reads it before every task. Here are the seven rules I find most load-bearing for real Rust work.

Rule 1: Owned types in public APIs, borrows inside implementations

pub fn parse(input: &'a str) -> Result<Foo<'a>, Error> looks clever and forces every caller to think about lifetimes. Prefer pub fn parse(input: &str) -> Result<Foo, Error> returning owned data. Use Cow<'_, str> only when zero-copy is genuinely the point. Lifetimes in pub signatures are a contract you can't change without a major version bump.

Rule 2: anyhow for binaries, thiserror for libraries — never both, never Box<dyn Error>

Library crates derive thiserror::Error on a typed enum, with #[from] for transparent wrapping and #[source] for chains. Binaries return anyhow::Result<T> and add .with_context(|| ...)? at every boundary so the error chain reads like a story. Mixing them or reaching for Box<dyn Error> loses both type information and context.

Rule 3: Never hold a std::sync::Mutex guard across .await

This is the single most common async bug AI writes. The guard isn't Send, the future captures it, the runtime moves the future to another thread, and you get a deadlock or a compiler error you don't understand. Use tokio::sync::Mutex for cross-await locking, or restructure the code to drop the std guard before any .await.

Rule 4: #![deny(unsafe_code)] at the crate root by default

Most crates have no business writing unsafe. Deny it at the root, and on the rare occasion you need it, every unsafe block carries a // SAFETY: comment explaining the invariants and every unsafe fn documents preconditions in a # Safety doc section. AI defaults to unsafe { transmute(...) } for "performance" — the rule kills that reflex.

Rule 5: clippy::pedantic + clippy::nursery + -D warnings in CI

#![warn(clippy::pedantic, clippy::nursery, missing_docs, rust_2018_idioms)]
#![deny(unsafe_op_in_unsafe_fn)]

CI runs cargo clippy --all-targets --all-features -- -D warnings. No blanket #[allow] at the crate root — only narrow allows with a comment explaining why. AI loves to silence lints; the rule forces it to fix the underlying issue instead.

Rule 6: No .unwrap() or .expect() in production paths

CI greps for \.unwrap\(\) and \.expect\( outside tests/, examples/, benches/ and fails the build. expect("...") is allowed only when the message documents an invariant the type system can't express ("checked above by is_some()"). Same goes for todo!(), unimplemented!(), and panic!() reachable from pub APIs — these are flow-control crimes, not error handling.

Rule 7: Repository tests hit a real database — never mock it

Use testcontainers (or a dockerised Postgres) for any code that talks to a database. Mocked DB tests pass while the actual SQL is broken — I've shipped that bug, you've shipped that bug, AI ships it by default. Async tests use #[tokio::test]; doc-tests run via cargo test --doc and gate API drift for free.

Wrapping up

These seven rules don't replace The Rust Programming Book — they encode the failure modes AI repeats most often when writing Rust. Owned types in public signatures, the right error crate for the job, no std mutex across await, denied unsafe, pedantic clippy, no unwrap in prod, real DB in tests. That's the line between "compiles, looks Rusty" and "I'd merge this."

Drop the file at the root of your crate. The next AI prompt produces Rust your future self won't have to apologise for at the post-mortem.

Free sample (this article + Gist): claudemd-rust-rules.md on GitHub Gist

Get the full CLAUDE.md Rules Pack (40+ languages and frameworks): oliviacraftlat.gumroad.com/l/skdgt