Rust
Language guide. Distills what agents get wrong; not a paste of
the Microsoft Pragmatic Rust Guidelines or a 200-rule dump. No scripts/.
Process skills that may load with this one: language-router Load-with list.
Iron law
Do not clone, unwrap, or unsafe your way around the type system.
Own, borrow, or share on purpose.
Tooling / verify
cargo fmt --check
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
Workspace: run on the touched crate, then the workspace if the API crossed
a crate boundary. Read the output. A green cargo check is not enough.
Idioms a linter misses
- Ownership is the API: owned value,
&T,&mut T.Arc<Mutex<T>>only when shared mutation is real and documented. - Invalid states are unrepresentable. Newtypes and enums over stringly modes. Parse at the boundary; do not re-validate in every function.
impl Traitin return position when there is one type.Box<dyn Trait>only for genuine heterogeneity.- Builders validate in
build(), not in every setter. Dropowns cleanup. No manual free paired with a comment.Fromfor error conversion in libraries.map_erronly when the target type is not yours to implementFromfor.- Modules stay balanced. Do not re-export the same item on two paths.
Errors
- Library crates: typed errors (
thiserroror equivalent already in the tree). Application glue may useanyhowif the crate already does. ?onResult/Option. Nounwrap/expecton production paths.expectin tests is fine when the panic message names the invariant.- Do not catch panics as control flow (
catch_unwindis Ask first).
Concurrency
Send/Syncare part of the API. Do not lie withunsafe impl.- Do not hold a
Mutex/RwLockguard across.await. - Blocking or CPU work:
spawn_blockingor a dedicated thread. Do not stall the runtime. - Channels and tasks have a shutdown story (cancel token, drop of sender, or JoinHandle awaited).
Testing
- Unit tests next to the code. Integration tests under
tests/. - Table-driven: array of cases +
for. Name the case. - Property tests for parsers, codecs, and invariants if the crate already uses proptest/quickcheck — do not add a framework unasked.
#[should_panic]is last resort; prefer aResultassertion.
PR review
- New
clone(): is it required, or is it silencing borrowck? - New
unsafe: SAFETY comment names a falsifiable invariant. Tests hit the boundary. Public API around it is safe to call. - Public types: is there one path to the item? Docs on every public item.
- Error type changes are API. Wrapping vs replacing matters.
- No
todo!()/unimplemented!()on the shipped path.
Security
- No hand-rolled crypto. Use the crate the project already picked.
- Path joins stay inside an allowlisted root. No
../trust. - Command args are arrays, never a shell string.
unsafe+ FFI: treat foreign data as untrusted until parsed into owned Rust types.
Always
clippyclean or anallowthat explains why.Resulton fallible public functions.- Tests for the new branch before calling it done (
tddif the change is behavior).
Ask first
- Any
unsafe. - Interior mutability as the default design (
RefCell, globalMutex). - MSRV bump, edition bump, or a new async runtime.
- Adding
unwrapin a library crate.
Never
unwrap()on production paths..clone()as a habit to please borrowck.unsafewithout// SAFETY:.transmuteor raw pointer arithmetic outside a reviewed boundary.- Catching panics as logic.
- Pasting the 33k-token Microsoft "all guidelines" file into context.
Red flags
- "I'll just clone it"
- "unwrap is fine, we know it's Some"
- "unsafe is faster"
- "
Box<dyn Trait>everywhere is simpler" - "cargo check passed so it's good"