rust-development

name	rust-development
description	Rust development workflow with quality gates, testing, and iteration patterns. Use when developing Rust code, running tests, or iterating on Rust projects.
allowed-tools	Read, Edit, Write, Bash, Grep, Glob, Task

Rust Development Workflow

Development patterns for Rust CLI tools and libraries, based on AllBeads and QDOS workflows.

Quality Gates

ALL THREE must pass before commits:

cargo fmt -- --check && cargo clippy -- -D warnings && cargo test

Run frequently during development, not just before commits.

Development Loop

1. Check and Build

# Fast check (no codegen)
cargo check

# Full build
cargo build

# Release build
cargo build --release

2. Run Tests

# All tests
cargo test

# Specific test
cargo test test_name

# With output
cargo test -- --nocapture

# Single-threaded (for tests with shared state)
cargo test -- --test-threads=1

3. Format and Lint

# Format code
cargo fmt

# Check formatting without changing
cargo fmt -- --check

# Lint with warnings as errors
cargo clippy -- -D warnings

# Auto-fix clippy suggestions
cargo clippy --fix --allow-dirty

4. Run the Binary

# Debug build
cargo run -- [args]

# Release build
cargo run --release -- [args]

# With specific features
cargo run --features "feature1,feature2" -- [args]

Project Structure

Standard Rust project layout:

project/
├── Cargo.toml          # Package manifest
├── Cargo.lock          # Dependency lock
├── src/
│   ├── main.rs         # Binary entry point
│   ├── lib.rs          # Library root (if both bin and lib)
│   └── module/
│       └── mod.rs
├── tests/              # Integration tests
├── benches/            # Benchmarks
└── examples/           # Example binaries

Error Handling Patterns

Application Errors (use anyhow)

use anyhow::{Context, Result};

fn main() -> Result<()> {
    let config = load_config()
        .context("Failed to load configuration")?;
    Ok(())
}

Library Errors (use thiserror)

use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("Invalid input: {0}")]
    InvalidInput(String),
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
}

Dependency Management

# Add dependency
cargo add serde --features derive

# Add dev dependency
cargo add --dev tokio-test

# Update dependencies
cargo update

# Check for outdated
cargo outdated  # requires cargo-outdated

Workspace Setup

For multi-crate projects:

# Cargo.toml (workspace root)
[workspace]
members = ["crate1", "crate2"]
resolver = "2"

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }

Performance Profiling

# Build with debug info for profiling
cargo build --release

# Time compilation
cargo build --timings

# Check binary size
cargo bloat --release  # requires cargo-bloat

Build Performance

Use mold linker (Linux)

Faster linking times:

# .cargo/config.toml
[target.'cfg(target_os = "linux")']
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

Install: sudo apt install mold or brew install mold

Use sccache for caching

Cache compiler artifacts across builds:

cargo install --locked sccache
export RUSTC_WRAPPER=sccache

# Add to shell profile for persistence
echo 'export RUSTC_WRAPPER=sccache' >> ~/.zshrc

Auto-derive macro

Reduce boilerplate for common derives:

macro_rules! auto_derived {
    ( $( $item:item )+ ) => {
        $(
            #[derive(Debug, Clone, PartialEq, Eq)]
            $item
        )+
    };
}

// Usage
auto_derived! {
    pub struct User {
        id: i64,
        name: String,
    }

    pub struct Config {
        host: String,
        port: u16,
    }
}

Add Serialize, Deserialize to the macro if using serde.

Common Patterns

Builder Pattern

pub struct Config {
    host: String,
    port: u16,
}

impl Config {
    pub fn builder() -> ConfigBuilder {
        ConfigBuilder::default()
    }
}

#[derive(Default)]
pub struct ConfigBuilder {
    host: Option<String>,
    port: Option<u16>,
}

impl ConfigBuilder {
    pub fn host(mut self, host: impl Into<String>) -> Self {
        self.host = Some(host.into());
        self
    }

    pub fn port(mut self, port: u16) -> Self {
        self.port = Some(port);
        self
    }

    pub fn build(self) -> Result<Config, &'static str> {
        Ok(Config {
            host: self.host.ok_or("host required")?,
            port: self.port.unwrap_or(8080),
        })
    }
}

Newtype Pattern

pub struct UserId(pub i64);
pub struct Email(String);

impl Email {
    pub fn new(s: impl Into<String>) -> Result<Self, &'static str> {
        let s = s.into();
        if s.contains('@') {
            Ok(Self(s))
        } else {
            Err("invalid email")
        }
    }
}

IDE Integration

For VS Code with rust-analyzer:

// .vscode/settings.json
{
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.cargo.features": "all"
}

Anti-Patterns

DON'T:

• Use .unwrap() in library code (use ? instead)
• Ignore clippy warnings
• Skip cargo fmt before commits
• Write tests after the fact

DO:

• Write code that passes fmt/clippy on first write
• Use Result<T, E> for fallible operations
• Run tests frequently during development
• Use #[must_use] for important return values