rust-dev

SKILL.md

---
name: rust-dev
description: Practical day-1 guide to building applications in Rust well. Covers the mental model (ownership, errors as values, traits-not-interfaces), day-1 decisions (String vs &str, Box vs Rc vs Arc, dyn vs impl Trait, anyhow vs thiserror), idioms to internalize early, anti-patterns to avoid, and a tight crate shortlist (tokio, serde, anyhow, clap, reqwest, tracing, axum, sqlx). Use when starting a new Rust project, learning Rust coming from Python/JS/Go/Java/C++, deciding on types and lifetimes, choosing crates, structuring modules, configuring Cargo.toml/clippy/rustfmt, writing tests, benchmarking, profiling, or speeding up builds, or whenever the user mentions Rust, cargo, ownership, borrow checker, lifetimes, traits, async Rust, testing, or "writing this in Rust".
metadata:
  version: "0.3.1"
  upstream: "rust@1.95.0, axum@0.8.9, reqwest@0.13.3, sqlx@0.9.0, jiff@0.2.24"
---

# Rust Development - Day 1

A practical foundation for writing Rust apps well from the first commit. Not a textbook. Focuses on the differences from other languages, the day-1 decisions that shape everything else, and the small set of crates that cover most real apps.

## When to Use

- Starting a new Rust project (CLI, service, library)
- Coming to Rust from Python, JavaScript, Go, Java/C#, or C++
- Choosing between owned/borrowed types, smart pointers, trait objects vs generics
- Picking error handling strategy (`anyhow` vs `thiserror`)
- Deciding which crates to reach for
- Configuring a minimal but opinionated `Cargo.toml`, clippy, and rustfmt

## Day-1 Setup

```bash
# 1. Install the toolchain (rustup is the toolchain manager)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Confirm components (rustfmt and clippy ship with stable, rust-src enables IDE features)
rustup component add rustfmt clippy rust-src

# 3. Create a project
cargo new my-app          # binary (src/main.rs)
cargo new --lib my-lib    # library (src/lib.rs)

# 4. The dev loop (memorize these four)
cargo check     # fast type-check, no codegen
cargo run       # build and run (binary)
cargo test      # build and run tests (incl. doctests)
cargo clippy    # lint (run before pushing)
cargo fmt       # format

# 5. Manage dependencies without editing Cargo.toml by hand
cargo add tokio --features full
cargo remove tokio
cargo update                 # recompute Cargo.lock within existing semver ranges
```

`cargo update` only moves within the version ranges already in `Cargo.toml`. Crossing a major version (`1.x` to `2.0`) needs a `Cargo.toml` edit or `cargo add <crate>@2`.

**rust-analyzer is mandatory.** It is the language server every editor uses (VS Code, Zed, Neovim, Helix, RustRover uses its own engine but is comparable). In VS Code, install the `rust-analyzer` extension and set `rust-analyzer.check.command` to `"clippy"` so you get lint feedback on save.

**Want a file watcher later?** `cargo install bacon`, then run `bacon` in your project. Not needed on day 1.

## The Rust Mental Model in 5 Ideas

Rust trades two things you take for granted in most languages (a garbage collector and exceptions) for compile-time guarantees about memory, data races, and error handling. The shape of the language follows from that trade.

### 1. Ownership: every value has exactly one owner

Think of values like physical objects. A book, a file, a network connection. At any moment, **one variable owns it**. You can:

- **Move it**: `let b = a;` hands ownership to `b`. `a` is gone.
- **Borrow it immutably**: `&a` lets others look at it. Many readers allowed.
- **Borrow it mutably**: `&mut a` lets one person modify it. Exclusive access.
- **Clone it**: `a.clone()` makes a deep copy. Both keep their own.

When the owner goes out of scope, the value is dropped (memory freed, file closed, lock released). No GC, no manual `free`. This is RAII, enforced by the compiler.

### 2. Aliasing XOR mutability

At any moment, a piece of data has **either**:
- one mutable reference (`&mut T`), **or**
- any number of immutable references (`&T`),

never both. This single rule is what eliminates data races and most use-after-free bugs. The borrow checker enforces it. When it complains, it is telling you your data ownership story is unclear, not that the language is being difficult.

### 3. Errors are values, not exceptions

There is no `try`/`catch`. Functions that can fail return `Result<T, E>`. Functions that can return nothing useful return `Option<T>`. The compiler forces you to handle both. The `?` operator propagates errors up the call stack with one character:

```rust
fn read_config() -> Result<Config, anyhow::Error> {
    let text = std::fs::read_to_string("config.toml")?;  // ? = early-return on Err
    let config = toml::from_str(&text)?;
    Ok(config)
}
```

There is no `null`. `Option<T>` is `None` or `Some(value)`. The compiler will not let you forget the `None` case.

### 4. Traits are not Java interfaces

A `trait` defines behavior. Types `impl` traits. So far so familiar. The differences:

- **Static dispatch is the default.** When you write `fn f<T: Display>(x: T)`, the compiler generates a separate copy of `f` for each concrete `T` you call it with (monomorphization, like C++ templates). Zero runtime overhead.
- **Dynamic dispatch is opt-in** via `dyn Trait` (typically `Box<dyn Trait>` or `&dyn Trait`). One vtable lookup per call.
- **No inheritance.** Traits compose. If you find yourself reaching for `Deref` to "extend" a type, stop and use composition or an enum.
- **Orphan rule**: you can `impl YourTrait for SomeoneElsesType` or `impl SomeoneElsesTrait for YourType`, but not both foreign. This keeps dependency resolution sane.

### 5. The borrow checker is a design oracle

The most common newcomer mistake is treating compiler errors as obstacles to silence. They are not. Almost every borrow-check error reveals a real issue with **who owns what**. When you get stuck, the question is rarely "how do I make this compile" and almost always "what is the actual ownership relationship I want here?" Read the error. The compiler is unusually informative.

## The 3 Questions for Every Function Signature

Before writing a function, ask: does it need to **own**, **read**, or **modify** the input?

```rust
fn consume(s: String)        // owns:    function takes responsibility, caller loses it
fn read(s: &str)             // reads:   function looks at it, caller keeps it
fn modify(s: &mut String)    // mutates: function changes it in place
```

Defaults that work 90% of the time:
- Function parameters: prefer `&str` over `String`, `&[T]` over `Vec<T>` (these are slices, accept both owned and borrowed callers).
- Function returns: return owned types (`String`, `Vec<T>`). Returning references means lifetimes; avoid until you need them.
- Struct fields: prefer **owned** types (`String`, `Vec<T>`). Storing `&str` in a struct is the single most common newcomer trap and it cascades lifetime annotations through every type that holds your struct.

## Day-1 Decision Table

One-line answers to the choices that come up first.

| Decision | Default | When to pick the other |
|---|---|---|
| `String` vs `&str` (struct field) | `String` | Almost never `&str` until you have a real reason and understand lifetimes |
| `String` vs `&str` (function param) | `&str` | Use `String` only if you must own/store it inside |
| `Vec<T>` vs `&[T]` (param) | `&[T]` | `Vec<T>` only if you must own |
| `Box<T>` vs `Rc<T>` vs `Arc<T>` | `Box<T>` (single owner, heap) | `Arc<T>` for shared ownership across threads. Avoid `Rc<T>` as default; use `Arc<T>` so you do not refactor when you go async |
| `RefCell<T>` vs `Mutex<T>` | `Mutex<T>` (or `RwLock<T>`) | Same reason: works in async/threads, while `RefCell` does not |
| `Option<T>` vs `Result<T, E>` | `Option<T>` for "no value", `Result<T, E>` for "failed for a reason" | If the absence carries meaning the caller should handle, `Result` |
| `dyn Trait` vs `impl Trait` / `<T: Trait>` | Generic (`<T: Trait>` or `impl Trait`) - static dispatch | `Box<dyn Trait>` when you need a heterogeneous collection (`Vec<Box<dyn Animal>>`) |
| Errors in app code | `anyhow::Result<T>` everywhere | - |
| Errors in library code | `thiserror`-derived enum | Never `Box<dyn Error>` in public library APIs - forces callers to downcast |
| `&self` vs `&mut self` vs `self` | `&self` for getters, `&mut self` for setters, `self` for builders/consuming ops | - |
| Module layout | Inline modules until a file gets long, then split | One module = one file is a Java/C# instinct, not a Rust one |

## Idioms to Internalize Early

These appear in nearly every Rust program. Learn them in week 1.

**`?` for error propagation.** Replaces nine lines of `match` with one character.
```rust
let body = reqwest::get(url).await?.text().await?;
```

**Iterator chains over manual loops.** Compile to the same machine code as hand-written loops (LLVM inlines closures). Idiomatic Rust is functional in style.
```rust
let active_emails: Vec<String> = users
    .iter()
    .filter(|u| u.active)
    .map(|u| u.email.clone())
    .collect();
```

**`match` exhaustiveness.** Add a new variant to an enum and every `match` that does not handle it becomes a compile error. Use this. It is one of the most powerful refactoring tools in any language.

**Let the compiler drive refactors.** The same trick works on structs: add a mandatory field with no `Default` and every existing constructor becomes a compile error - a free, exhaustive worklist of every site to update.

**`if let` and `let else`** for the common single-arm match.
```rust
if let Some(name) = user.name { println!("hi {name}"); }

let Some(name) = user.name else { return Err(anyhow!("no name")); };
// `name` is in scope from here on, no nesting
```

**`From` / `Into` for type conversions.** Implement `From`, get `Into` for free. `?` uses `From` to convert error types automatically.

**Combinators on `Option` / `Result`.** Reach for `.map`, `.and_then`, `.unwrap_or`, `.unwrap_or_else`, `.ok_or` before reaching for `match`.

**Derive macros.** `#[derive(Debug, Clone, PartialEq)]` gets you 80% of the boilerplate for free. Add `#[derive(Serialize, Deserialize)]` for JSON.

**Recent sugar (Rust 1.95+).** Two stabilized features worth knowing: `cfg_select!` is a compile-time `match` over `cfg` predicates (replaces most uses of the `cfg-if` crate), and `if let` guards now work on `match` arms (`match x { Some(v) if let Ok(n) = v.parse::<i32>() => ... }`).

## Coming From X, Here Is What Bites You

**From Python or JavaScript:**
- `let b = a;` for a heap value (like `String`, `Vec`) **moves** it. `a` is no longer usable. Use `&a` to borrow or `a.clone()` to copy.
- No null. `Option<T>` is forced on you.
- No exceptions. `Result<T, E>` and `?`. The compiler will not let you ignore errors.
- No inheritance. Composition + traits + enums.
- Variables are immutable by default. Add `mut` to mutate. Same for references: `&` vs `&mut`.
- Integer types are explicit and indexing requires `usize`.

**From Go:**
- Errors as values - same instinct, but use `?` instead of `if err != nil`.
- No `nil`. `Option<T>`.
- No GC and no goroutines: ownership + borrowing, async/await with `tokio`. The async model is cooperative (`await` is an explicit yield point), not preemptive.
- `interface{}` becomes traits. Default to generics for static dispatch; `Box<dyn Trait>` only when you need it.
- Static linking is the default. Binaries are bigger but self-contained.
- `panic!` should be reserved for unrecoverable bugs in app code; do not use it as Go-style "log and continue".

**From Java or C#:**
- Traits are not interfaces with virtual dispatch by default. `<T: Trait>` is monomorphized. `dyn Trait` is the opt-in dynamic version.
- No null references. `Option<T>`.
- No exceptions. `Result<T, E>` and `?`.
- No class inheritance. Use enums for sum types, traits for shared behavior.
- No GC: ownership and borrowing decide lifetimes. `Arc<T>` is the closest thing to a Java reference.
- Generics are monomorphized, not type-erased.

**From C++:**
- Like RAII, but the borrow checker enforces it at compile time.
- No copy/move constructors. `Clone` is explicit and `Copy` is a marker trait for cheap bitwise copies.
- No undefined behavior in safe code (in theory).
- `&` is a compile-time-checked borrow, not a raw pointer. Raw pointers exist (`*const T`, `*mut T`) but require `unsafe` to dereference.
- Smart pointers are `Box<T>` (`unique_ptr`), `Rc<T>` (`shared_ptr`, single thread), `Arc<T>` (`shared_ptr`, thread-safe).
- Macros are hygienic. Procedural macros (derive, attribute, function-like) are how `serde`, `tokio::main`, etc. work.

## The Crate Shortlist

These cover most real apps. Add them as needed; they are not all required.

| Crate | What it gives you |
|---|---|
| `serde` + `serde_json` | Serialization. `#[derive(Serialize, Deserialize)]` and you are done |
| `tokio` | Async runtime. `#[tokio::main]`, `tokio::spawn`, async I/O |
| `anyhow` | App error type. `anyhow::Result<T>`, `bail!`, `context()` |
| `thiserror` | Library error enums. `#[derive(thiserror::Error)]` |
| `clap` | CLI argument parsing. `#[derive(Parser)]` and you have a CLI |
| `reqwest` | HTTP client. Async by default, blocking feature available |
| `tracing` + `tracing-subscriber` | Structured logging. The default for any async code (replaces `log`) |
| `axum` | Web framework. Built on `tokio` + `hyper` + `tower`. The 2026 default |
| `sqlx` | Database access. Async, compile-time checked queries. PostgreSQL, MySQL, SQLite |
| `chrono` | Dates and times. The maintainer announced soft-deprecation in Jan 2026 and recommends `jiff` for new code. `jiff` (BurntSushi) is the successor but still pre-1.0 as of May 2026. Pick `chrono` for `serde`/`sqlx` integration today, `jiff` if you can tolerate pre-1.0 churn |

See `references/crate-shortlist.md` for one minimal example each.

## Top Anti-Patterns to Avoid

These are the mistakes that show up in every newcomer's code review. Avoid them.

1. **Storing `&str` (or any reference) in a struct.** Causes lifetime annotations to cascade through every caller. Use `String` until you have a profiler-backed reason not to.
2. **Reaching for `Rc<RefCell<T>>` (or `Arc<Mutex<T>>`) to simulate Python/JS object graphs.** First ask whether you need shared mutable state at all - usually plain ownership, or passing data through a channel, is cleaner. When you genuinely do, prefer `Arc<Mutex<T>>` over `Rc<RefCell<T>>` so adding threads later is not a refactor.
3. **`Box<dyn Error>` in library public APIs.** Forces callers to downcast. Define a typed error enum with `thiserror`. `Box<dyn Error>` is acceptable inside a binary, never in a published library.
4. **`.unwrap()` and `.expect()` outside prototypes and tests.** Use `?` and propagate - for an `Option`, `.ok_or_else(|| anyhow!(...))?` does the conversion. When a value genuinely cannot be absent, prefer `.expect("why it cannot fail")` over `.unwrap()`: the message is the comment that documents the invariant.
5. **Brute-force `.clone()` until it compiles.** Sometimes cloning is right, but if you are scattering `.clone()` to silence the borrow checker, the design is wrong. Step back and ask the 3 questions about who owns what.
6. **Trying to inherit via `Deref`**. `Deref` is for smart-pointer-like wrappers, not for OOP-style "extends". Use composition.
7. **Reaching for `unsafe`.** App developers should essentially never need it. `unsafe` does not turn off the borrow checker; it lets you do five specific things (deref raw pointers, call unsafe functions, access mutable statics, implement unsafe traits, access union fields) with the contract that you have manually verified the invariants.

## What to Defer

You do not need these on day 1. Some you may never need.

- **Lifetimes in struct fields.** Avoid by using owned types. The day you genuinely need them, you will know.
- **`Pin`, `Future` internals, manual `poll` impls.** Just write `async fn` and `.await`.
- **`unsafe` and FFI.** Almost never for app code.
- **Procedural macros.** Library author territory.
- **Higher-ranked trait bounds (`for<'a>`)**, variance, `PhantomData`. Expert territory.
- **`Cell`, `OnceCell`, `LazyLock`, `MaybeUninit`.** Reach for these when you have a specific reason.

## Minimal Cargo.toml

Single-crate, edition 2024, opinionated lints. Drop into a fresh project.

```toml
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"

[dependencies]

[dev-dependencies]

[profile.release]
lto = "thin"
codegen-units = 1

# =============================================================================
# Lints. Loose-but-helpful: deny obvious bugs, warn on common smells, leave
# room to learn. Upgrade to clippy::pedantic later if you want the full ride.
# =============================================================================
[lints.rust]
unsafe_code     = "forbid"   # downgrade to "deny" if you do FFI
unreachable_pub = "warn"

[lints.clippy]
all = { level = "deny", priority = -1 }
# Idiomatic helpers
# Note: uninlined_format_args moved to clippy::pedantic (allow-by-default)
# in Rust 1.89.0 (mid-2025), so an explicit warn keeps the nudge active.
uninlined_format_args         = "warn"
semicolon_if_nothing_returned = "warn"
implicit_clone                = "warn"
# Smells in non-prototype code
dbg_macro   = "warn"
todo        = "warn"
print_stdout = "warn"   # use `tracing::info!` instead in real apps
```

## rustfmt.toml

```toml
style_edition = "2024"
edition       = "2024"
```

That is enough. rustfmt's defaults are good. Some teams add `use_small_heuristics = "Max"` to keep more code on single lines. Fancy options like `imports_granularity` and `group_imports` are still nightly-only as of May 2026.

Run `cargo fmt` before you start editing (or commit any pre-existing drift on its own) so formatting noise stays out of your diff, and make `cargo fmt --check` its own CI step.

## rust-toolchain.toml (optional but recommended)

Pins the toolchain per-project so everyone on the team uses the same Rust.

```toml
[toolchain]
channel    = "stable"
components = ["rustfmt", "clippy", "rust-src"]
profile    = "minimal"
```

## .gitignore

```
/target
```

Commit `Cargo.lock`. Since 2023 it is the recommended default for every crate type, libraries included (`cargo new` tracks it); a library may still choose to ignore it.

## Project Structure

```
my-app/
  src/
    main.rs        # binary entry point: fn main()
    lib.rs         # OR a library crate root
    config.rs      # module: declared as `mod config;` in main.rs/lib.rs
    api/           # nested module
      mod.rs       # OR `api.rs` next to api/ folder (2018+ style preferred)
      users.rs
  tests/           # integration tests (each file is its own crate)
    smoke.rs
  Cargo.toml
  Cargo.lock
  rust-toolchain.toml
  rustfmt.toml
  .gitignore
```

Inline modules with `mod { ... }` until a file gets long, then split. Do not pre-split.

## Learning Path

1. **The Rust Book** (https://doc.rust-lang.org/book/) - canonical, free, current. The interactive Brown University version (https://rust-book.cs.brown.edu/) adds quizzes and visualizations.
2. **Rustlings** (https://github.com/rust-lang/rustlings) - exercises in parallel with The Book.
3. **100 Exercises to Learn Rust** (https://rust-exercises.com/) - alternative or supplement to Rustlings, slightly newer.
4. **Rust for Rustaceans** (Jon Gjengset) - the post-beginner book. Read after you are comfortable.
5. **Zero to Production in Rust** (Luca Palmieri) - if you are building a backend service. Note: the book uses `actix-web` while `axum` is the 2026 default; the patterns translate cleanly.

For looking up syntax: **Rust by Example** (https://doc.rust-lang.org/rust-by-example/).

For curated crate recommendations: **blessed.rs** (https://blessed.rs/crates).

## Reference Docs

Detailed material lives in `references/`. Read each when you hit the topic.

- **ownership-and-types.md** - ownership, borrowing, lifetimes, `String`/`&str`/`Cow`, slices, smart pointers, the self-referential struct trap
- **error-handling.md** - `Result`, `?`, `anyhow` vs `thiserror` patterns, custom error enums, when `panic!` is appropriate
- **traits-and-generics.md** - traits as bounds, `dyn` vs `impl Trait` vs generics, common derives, `From`/`Into`/`Display`/`Debug`, blanket impls, the orphan rule
- **async-basics.md** - `tokio`, `#[tokio::main]`, `.await`, `Send`/`Sync`, common pitfalls (blocking in async, `MutexGuard` across `.await`)
- **crate-shortlist.md** - minimal usage example for each of the 8 crates above
- **testing.md** - what to test and what to skip, pragmatic test organization, keeping the suite fast, the minimal high-value tool kit
- **dev-environment.md** - the fast build loop, build caching (sccache, rust-cache), platform-aware linker guidance, file watchers
- **performance.md** - profiling before optimizing, benchmarking with criterion/divan, the real runtime wins