rust

Rust Cursor Rules

You are an expert Rust developer. Follow these rules:

Ownership & Borrowing

• Prefer borrowing (&T, &mut T) over cloning — .clone() is a code smell unless the type is cheap to clone (small Copy types, Arc)
• Use explicit lifetime annotations only when the compiler can't infer them (multiple references in, one reference out). Don't litter code with 'a when elision handles it
• Parameters: &str over &String, &[T] over &Vec<T> — accepting the owned type forces callers to allocate unnecessarily. The reference form accepts both owned and borrowed
• Cow<'_, str> when a function sometimes allocates and sometimes doesn't — avoids cloning in the common path while allowing owned data when needed
• impl AsRef<str> or Into<String> for parameters that should accept both &str and String ergonomically

Error Handling

• thiserror for library errors (derive Error with structured variants). anyhow for application code (captures any error with context)
• Never .unwrap() in production code — it panics with no context. .expect("reason why this should never fail") is acceptable only for genuinely impossible states (verified by prior logic)
• ? operator for propagation — it's the entire error handling strategy in Rust. Design functions to return Result<T, E> so ? composes naturally
• Add context with .context("what we were trying to do") (anyhow) or .map_err(|e| MyError::Fetch { source: e }) (thiserror) — raw propagation without context creates opaque error chains
• panic! only for programmer bugs (violated invariants, unreachable states). Never for user input, network errors, or file operations

Type System

• Newtype pattern for type safety: struct UserId(u64) prevents passing an OrderId where a UserId is expected — zero runtime cost
• Enums with data over boolean flags: enum Status { Active, Suspended { reason: String, until: DateTime } } not is_active: bool, suspension_reason: Option<String>
• Derive Debug, Clone, PartialEq at minimum on data types. Add Serialize, Deserialize (serde) when the type crosses boundaries (API, storage, config)
• Builder pattern (or Default + struct update) for types with many optional fields — don't make callers construct 10-field structs manually