Rust Ownership skill for Claude Code

Done well means: the code compiles without .clone() used as a sedative, each value has one obvious owner, lifetimes appear only where a struct or function truly borrows, errors carry context, and cargo clippy --all-targets -- -D warnings is clean.

Ground rules

• Read the full rustc message, including the “borrow later used here” span. The fix is usually moving that later use, not adding a clone.
• Prefer restructuring (shorter borrows, splitting structs, passing indices or IDs) over Rc<RefCell<_>>. Interior mutability is a design choice, not an error fix.
• Owned types in structs by default (String, Vec<T>). Reach for &'a str fields only for short-lived views where profiling shows allocation matters.
• Function parameters: borrow (&str, &[T], &T) unless the function stores or consumes the value; then take ownership (String, Vec<T>, T).
• No unwrap()/expect() in library code paths that can fail on input. expect with a message stating the invariant is acceptable for true invariants.

Workflow for a borrow checker error

- [ ] 1. Identify the error code (rustc --explain E0502 for the canonical example)
- [ ] 2. Mark the three spans: where the borrow starts, the conflicting action, the later use
- [ ] 3. Ask: can the later use move earlier, or the borrow end sooner?
- [ ] 4. Ask: does this need two owners, or one owner and a reference passed down?
- [ ] 5. Apply the smallest structural fix from the table below
- [ ] 6. Re-run cargo check; if a new error appears in a different place, repeat
- [ ] 7. Run clippy and tests

For the error-code catalog with before/after fixes, read references/borrow-errors.md when the error is not one of the common patterns below.

Fix patterns, cheapest first

Symptom	Fix
Mutate while iterating a collection	Collect indices/keys first, then mutate; or use retain, iter_mut, drain(..)
Borrow one field mutably, another immutably via &mut self method	Borrow fields directly (let a = &mut self.a; let b = &self.b;) or split into a helper taking the fields
Value moved into closure, used after	Clone before the closure only the cheap part, or restructure so the closure runs last; move + Arc for threads
Value used after move into function	Pass &value; if callee needs ownership, clone at that call or return the value back
Returning reference to a local	Return the owned value (String, Vec)
HashMap get-then-insert	map.entry(k).or_insert_with(..)
Option field needs taking out of &mut self	self.field.take() or std::mem::replace / mem::take
Self-referential struct	Store indices or offsets instead of references; or separate the owner from the view
Graph / cyclic data	Arena + usize IDs (or slotmap); Rc + Weak only if arenas do not fit

// E0502: cannot borrow `v` as mutable because it is also borrowed as immutable
let first = &v[0];
v.push(4);            // conflict
println!("{first}");

// Fix: end the shared borrow before mutating (copy the value out if it is Copy)
let first = v[0];
v.push(4);
println!("{first}");

Choosing ownership containers

Need	Use
Heap allocate, single owner, recursive type	Box<T>
Shared read-only, single thread	Rc<T>
Shared read-only, across threads	Arc<T>
Shared + mutable, single thread	Rc<RefCell<T>> (runtime borrow panics possible)
Shared + mutable, threads, short critical sections	Arc<Mutex<T>> (parking_lot or std)
Many readers, rare writers	Arc<RwLock<T>>
Simple counter/flag across threads	AtomicU64, AtomicBool
Maybe-owned string (avoid alloc on fast path)	Cow<'a, str>
Cheap clones of large immutable strings/slices	Arc<str>, Arc<[T]>

Never hold a std::sync::Mutex guard across .await; use tokio::sync::Mutex only when the lock must span an await, otherwise scope the guard in a block.

Lifetimes

• Elision covers most functions: one input reference, or &self, gives the output the same lifetime. Write lifetimes only when the compiler asks.
• Name lifetimes by meaning when there are several: 'src, 'buf.
• T: 'static means “owns all its data or holds only ‘static references”, not “lives forever”. Thread spawns and tokio::spawn require it; pass owned data or Arc.
• Struct holding a reference: struct Parser<'a> { input: &'a str }. Every method returning slices of input should return &'a str, not &str tied to &self.
• impl Trait in return position captures all in-scope lifetimes in edition 2024; use + use<'a> precise capturing when you need to restrict it.

Error handling

Crate kind	Use
Library (others match on errors)	thiserror enum per module or crate
Binary / application	anyhow::Result with .context() at each layer
Both in one workspace	thiserror in lib crates, anyhow in the bin

// library
#[derive(Debug, thiserror::Error)]
pub enum ConfigError {
    #[error("config file not found at {path}")]
    NotFound { path: std::path::PathBuf },
    #[error("invalid TOML in config")]
    Parse(#[from] toml::de::Error),
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

// application
use anyhow::{Context, Result};
fn load(path: &std::path::Path) -> Result<Config> {
    let text = std::fs::read_to_string(path)
        .with_context(|| format!("reading config {}", path.display()))?;
    let cfg = toml::from_str(&text).context("parsing config")?;
    Ok(cfg)
}

• ? converts via From; add #[from] only when the conversion is unambiguous.
• Do not stringify errors (map_err(|e| e.to_string())); it destroys the source chain.
• main can return anyhow::Result<()>; print with {:#} or {:?} to see the chain.

Cargo and tooling

cargo new --lib mylib          # or --bin
cargo add serde --features derive
cargo add --dev proptest
cargo check                    # fastest feedback loop
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --all -- --check
cargo test --all-features
cargo tree -d                  # duplicate dependency versions
cargo update -p some-crate     # bump one lockfile entry

Workspace root Cargo.toml:

[workspace]
resolver = "3"                 # edition 2024 default
members = ["crates/*"]

[workspace.package]
edition = "2024"
rust-version = "1.85"

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
thiserror = "2"
anyhow = "1"

[workspace.lints.clippy]
pedantic = { level = "warn", priority = -1 }
unwrap_used = "warn"
module_name_repetitions = "allow"

Member crates use serde.workspace = true and [lints] workspace = true.

Idioms clippy and reviewers expect

• Iterators over index loops: items.iter().filter(..).map(..).collect::<Vec<_>>().
• if let Some(x) = opt / let Some(x) = opt else { return ... }; (let-else).
• impl From<A> for B rather than ad-hoc to_b(); implement Display for user-facing types, derive Debug everywhere.
• Accept impl AsRef<Path> or &Path for paths; impl Into<String> for constructors that store strings.
• #[must_use] on builders and functions whose result must not be ignored.
• Newtypes (struct UserId(u64);) to stop mixing IDs.

Gotchas

• .clone() on an Arc is cheap; on a Vec<String> it is not. Clippy’s redundant_clone (nursery) and reading the type tell you which.
• RefCell borrow errors are runtime panics (already mutably borrowed); they appear in production, not in cargo check.
• async fn in traits is stable, but the returned futures are not Send by default for generic callers; use the trait_variant crate or explicit impl Future + Send.
• Deadlocks: acquiring two Mutexes in different orders in different code paths. Define a lock order or merge the state.
• unsafe to bypass the borrow checker is almost never correct; if you think you need it, document the invariant and run cargo miri test.
• Edition 2024 changes temporaries in if let and tail expressions; when migrating, run cargo fix --edition and review drop-order sensitive code (locks, guards).

Verification

1. cargo check and cargo build --all-targets succeed.
2. cargo clippy --all-targets --all-features -- -D warnings clean.
3. cargo test passes; for concurrency changes also run tests under --release.
4. Count clones you added: git diff | grep -c '\.clone()'. Justify each in the summary.
5. For unsafe or tricky lifetimes: cargo +nightly miri test on the affected module.