# Rust Developer

> Comprehensive Rust development guidelines based on 6 months of code reviews. Use when writing Rust code, debugging Rust issues, or reviewing Rust PRs. Covers error handling, file I/O safety, type safety patterns, performance optimization, common footguns, and fundamental best practices. Perfect for both new and experienced Rust developers working on CLI tools, hooks, or production code. Use when this capability is needed.

- Skill: `tomevault-io/rust-developer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/rust-developer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rust-developer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/rust-developer

---


# Rust Developer Guide

## Purpose

Provides comprehensive Rust development best practices learned from 6 months of code reviews across the Catalyst project. Helps avoid common mistakes, write idiomatic Rust, and build safe, performant production code.

## When to Use This Skill

Automatically activates when you:
- Write or modify Rust code (`.rs` files)
- Debug Rust compiler errors or warnings
- Review Rust pull requests
- Ask about Rust best practices
- Implement CLI tools or hooks
- Work with error handling, file I/O, or type safety
- Optimize Rust code for performance
- Question Rust patterns or idioms

---

## Quick Start

**New to Rust or this codebase?**
Start with [Quick Reference Checklist](../../../docs/rust-lessons/quick-reference.md) - Scannable checklist of all 20+ rules

**Working on specific topic?**
Jump to the relevant resource file below

**Made a specific mistake?**
Check [Common Footguns](../../../docs/rust-lessons/common-footguns.md)

**Writing production code?**
Review [Error Handling Deep Dive](../../../docs/rust-lessons/error-handling-deep-dive.md) first

---

## Resource Files

### Quick Reference (Start Here)

**[quick-reference.md](../../../docs/rust-lessons/quick-reference.md)** - 400-line scannable checklist

- All 20+ lessons in one place
- Rule + Quick check + Example + Link to deep dive
- Perfect for code review or quick lookup
- Can be scanned in under 2 minutes

### Additional Patterns

**[rust-patterns.md](rust-patterns.md)** - ~555 lines

**When to use:**
- Choosing between thiserror and anyhow
- Input validation at boundaries
- Concurrent database access
- Preventing SQL injection
- Ownership patterns (borrow vs owned)
- Testing error paths

**Topics covered:**
- thiserror vs anyhow (when to use each)
- Input validation with validator crate
- Arc<Mutex<T>> for thread-safe shared state
- Parameterized queries for SQL injection prevention
- Ownership patterns (borrow params, return owned)
- Testing error paths explicitly
- Match-based error classification

**Skill level:** Intermediate

**Complements:** Error Handling, Type Safety, Common Footguns

---

### Deep-Dive Guides (Comprehensive Learning)

#### 1. Fundamentals
**[fundamentals-deep-dive.md](../../../docs/rust-lessons/fundamentals-deep-dive.md)** - ~450 lines

**When to use:**
- Setting up a new Rust project
- Organizing imports and dependencies
- Setting up tracing/logging
- First-time Rust contributor

**Topics covered:**
- Imports and code organization
- Tracing subscribers (avoid duplicated setup)
- CLI user feedback patterns
- TTY detection for colored output
- Avoiding duplicated logic

**Skill level:** Beginner

---

#### 2. Error Handling
**[error-handling-deep-dive.md](../../../docs/rust-lessons/error-handling-deep-dive.md)** - ~600 lines

**When to use:**
- Using `Option<T>` or `Result<T, E>`
- Deciding between `unwrap()`, `expect()`, and `?`
- Path operations that can fail
- Converting between error types

**Topics covered:**
- Option handling patterns (unwrap_or, unwrap_or_else, map_or)
- Result handling and error propagation
- When to use expect() vs unwrap() vs ?
- Path operation footguns (display().to_string())
- Context with anyhow or thiserror

**Skill level:** Beginner/Intermediate

---

#### 3. File I/O Safety
**[file-io-deep-dive.md](../../../docs/rust-lessons/file-io-deep-dive.md)** - ~500 lines

**When to use:**
- Writing files (especially config/state files)
- Creating directories
- Working with temporary files
- Testing file operations

**Topics covered:**
- Atomic file writes with tempfile crate
- Parent directory creation patterns
- NamedTempFile usage
- Testing file I/O (in-memory, temp dirs)
- Avoiding TOCTOU races

**Skill level:** Intermediate

---

#### 4. Type Safety
**[type-safety-deep-dive.md](../../../docs/rust-lessons/type-safety-deep-dive.md)** - ~650 lines

**When to use:**
- Validating string inputs
- Designing APIs with constrained values
- Providing user-friendly error messages
- Converting magic strings to types

**Topics covered:**
- Constants → Enums progression
- Newtype pattern for preventing type confusion
- Validation at boundaries
- User-friendly error messages
- "Did you mean?" suggestions with edit distance
- Pattern matching for exhaustiveness

**Skill level:** Intermediate

---

#### 5. Performance Optimization
**[performance-deep-dive.md](../../../docs/rust-lessons/performance-deep-dive.md)** - ~450 lines

**When to use:**
- Optimizing hot paths
- Processing large datasets
- Reducing allocations
- Profiling performance bottlenecks

**Topics covered:**
- Loop optimizations (pre-allocation, iteration patterns)
- Zero-copy abstractions (AsRef, Borrow, Cow)
- Pre-compilation patterns (static regexes, lazy_static)
- Performance profiling tools
- Benchmarking with criterion

**Skill level:** Intermediate/Advanced

---

#### 6. Common Footguns
**[common-footguns.md](../../../docs/rust-lessons/common-footguns.md)** - ~400 lines

**When to use:**
- Debugging borrow checker errors
- Path operation failures
- Race conditions in file operations
- Unexpected behavior in production

**Topics covered:**
- Path operations (display().to_string() vs to_path_buf())
- TOCTOU (Time-of-Check-Time-of-Use) races
- Borrow checker with HashSet and collections
- Common pitfalls and how to avoid them

**Skill level:** Mixed (Beginner through Advanced)

---

## Learning Paths

### Path 1: Beginner (First PRs)

Recommended reading order for new Rust developers:

1. **[Fundamentals](../../../docs/rust-lessons/fundamentals-deep-dive.md)**
   - Imports and code organization
   - Tracing subscribers
   - Avoiding duplicated logic

2. **[Error Handling](../../../docs/rust-lessons/error-handling-deep-dive.md)** (Sections 1-2)
   - Option handling basics
   - When to use expect vs unwrap

3. **[Quick Reference](../../../docs/rust-lessons/quick-reference.md)**
   - Scan all rules to build awareness

**Goal:** Avoid the most common beginner mistakes

---

### Path 2: Intermediate (Production Code)

For developers writing production-quality Rust:

1. **[Error Handling](../../../docs/rust-lessons/error-handling-deep-dive.md)** (Complete)
   - All Option/Result patterns
   - Path operation footguns

2. **[Rust Patterns](rust-patterns.md)** (NEW!)
   - thiserror vs anyhow
   - Input validation
   - Ownership patterns
   - Arc<Mutex<T>> for concurrency
   - SQL injection prevention
   - Testing error paths

3. **[File I/O Safety](../../../docs/rust-lessons/file-io-deep-dive.md)**
   - Atomic writes
   - Safe file operations
   - Testing file I/O

4. **[Type Safety](../../../docs/rust-lessons/type-safety-deep-dive.md)**
   - Constants → Enums progression
   - Validation patterns
   - User-friendly errors

5. **[Common Footguns](../../../docs/rust-lessons/common-footguns.md)**
   - TOCTOU races
   - Borrow checker patterns

**Goal:** Write robust, safe production code

---

### Path 3: Advanced (Performance & Safety)

For optimizing critical code paths:

1. **[Performance](../../../docs/rust-lessons/performance-deep-dive.md)**
   - Loop optimizations
   - Zero-copy abstractions
   - Profiling techniques

2. **[Common Footguns](../../../docs/rust-lessons/common-footguns.md)**
   - Borrow checker with collections
   - Advanced safety patterns

3. Review all deep-dives for edge cases

**Goal:** Maximize performance while maintaining safety

---

## Code Review Checklist

When reviewing Rust PRs, check against:

1. **[Quick Reference](../../../docs/rust-lessons/quick-reference.md)** - All 20+ rules
2. **Error Handling** - Are Options/Results handled safely?
3. **File I/O** - Are writes atomic? Are parent dirs created?
4. **Type Safety** - Are magic strings replaced with enums?
5. **Performance** - Are hot paths optimized? Pre-allocated?
6. **Common Footguns** - Any TOCTOU races? Path operations safe?

---

## Quick Topic Lookup

| Topic | Resource |
|-------|----------|
| **anyhow vs thiserror** | [Rust Patterns](rust-patterns.md) |
| **Arc<Mutex<T>> Pattern** | [Rust Patterns](rust-patterns.md) |
| **Atomic File Writes** | [File I/O Deep Dive](../../../docs/rust-lessons/file-io-deep-dive.md) |
| **Borrow Checker Issues** | [Common Footguns](../../../docs/rust-lessons/common-footguns.md) |
| **CLI User Feedback** | [Fundamentals](../../../docs/rust-lessons/fundamentals-deep-dive.md) |
| **Concurrent Database Access** | [Rust Patterns](rust-patterns.md) |
| **Error Classification** | [Rust Patterns](rust-patterns.md) |
| **Error Handling Patterns** | [Error Handling Deep Dive](../../../docs/rust-lessons/error-handling-deep-dive.md) |
| **Enums vs Strings** | [Type Safety Deep Dive](../../../docs/rust-lessons/type-safety-deep-dive.md) |
| **expect() vs unwrap()** | [Error Handling Deep Dive](../../../docs/rust-lessons/error-handling-deep-dive.md) |
| **Newtype Pattern** | [Type Safety Deep Dive](../../../docs/rust-lessons/type-safety-deep-dive.md) |
| **Input Validation** | [Rust Patterns](rust-patterns.md) |
| **Loop Optimizations** | [Performance Deep Dive](../../../docs/rust-lessons/performance-deep-dive.md) |
| **Option Handling** | [Error Handling Deep Dive](../../../docs/rust-lessons/error-handling-deep-dive.md) |
| **Ownership Patterns** | [Rust Patterns](rust-patterns.md) |
| **Path Operations** | [Common Footguns](../../../docs/rust-lessons/common-footguns.md) |
| **Performance Profiling** | [Performance Deep Dive](../../../docs/rust-lessons/performance-deep-dive.md) |
| **SQL Injection Prevention** | [Rust Patterns](rust-patterns.md) |
| **Testing Error Paths** | [Rust Patterns](rust-patterns.md) |
| **TOCTOU Races** | [Common Footguns](../../../docs/rust-lessons/common-footguns.md) |
| **Tracing Setup** | [Fundamentals](../../../docs/rust-lessons/fundamentals-deep-dive.md) |
| **Validation Patterns** | [Type Safety Deep Dive](../../../docs/rust-lessons/type-safety-deep-dive.md) |

---

## Catalyst-Specific Patterns

### Project Structure

```
catalyst/
├── catalyst-core/         # Core library (shared logic)
│   ├── src/
│   │   └── lib.rs
│   └── Cargo.toml
└── catalyst-cli/          # CLI binaries (hooks, tools)
    ├── src/bin/
    │   ├── file_analyzer.rs
    │   ├── skill_activation_prompt.rs
    │   └── settings_manager.rs
    └── Cargo.toml
```

### Common Patterns in This Project

**Binary Structure:**
```rust
use thiserror::Error;
use tracing::{debug, error};

#[derive(Error, Debug)]
enum MyError {
    #[error("[CODE] {message}\n{context}")]
    SomeError { message: String, context: String },
}

fn run() -> Result<(), MyError> {
    // Initialize tracing (do once in main, not in libraries)
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::try_from_default_env()
                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
        )
        .init();

    // Business logic here
    Ok(())
}

fn main() {
    if let Err(e) = run() {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}
```

**Custom Error Types with thiserror:**
```rust
#[derive(Error, Debug)]
enum ToolError {
    #[error("[ERR001] File not found: {}\nTry: touch {}", path.display(), path.display())]
    FileNotFound { path: PathBuf },

    #[error("[ERR002] {0}")]
    Io(#[from] std::io::Error),
}
```

**Structured Logging:**
```rust
error!(
    error_code = "ERR001",
    error_kind = "FileNotFound",
    path = %path.display(),
    "File operation failed"
);
```

---

## Integration with Catalyst Workflow

### When This Skill Activates

This skill automatically activates when:

1. **File Triggers:**
   - Editing any `.rs` file in the project
   - Creating new Rust binaries or libraries
   - Modifying `Cargo.toml` files

2. **Prompt Triggers:**
   - Mentioning "Rust", "cargo", "rustc"
   - Asking about error handling, Option, Result
   - Discussing performance optimizations
   - Requesting code reviews for Rust

3. **Content Triggers:**
   - Code contains Rust-specific patterns (Result, Option, impl, trait)
   - Working with thiserror, anyhow, serde
   - Using Rust ecosystem crates

### Complementary Skills

This skill works well with:

- **skill-developer** - When creating new skills in Rust
- **error-tracking** - When integrating Sentry (though we don't use it for Rust yet)

---

## Contributing New Lessons

Found a new Rust footgun or best practice? See:

**[CONTRIBUTING.md](../../../docs/rust-lessons/CONTRIBUTING.md)** - Complete guide for adding lessons

Quick steps:
1. Add to appropriate deep-dive guide
2. Update [quick-reference.md](../../../docs/rust-lessons/quick-reference.md)
3. Maintain cross-references
4. Include before/after examples

---

## Version History

**Current Version:** 1.0
**Based on:** Rust Lessons Learned v2.0 (6 months of code reviews, Phases 0-2.6)
**Last Updated:** 2025-11-02
**Maintainer:** Catalyst Project Team

---

## Quick Links

- 🚀 **[Quick Reference Checklist](../../../docs/rust-lessons/quick-reference.md)** - Start here
- 📚 **[All Deep-Dive Guides](../../../docs/rust-lessons/)** - Comprehensive learning
- 🔍 **[Common Footguns](../../../docs/rust-lessons/common-footguns.md)** - Avoid mistakes
- 📖 **[Navigation Guide](../../../docs/rust-lessons/index.md)** - Full documentation index

---

**Ready to write better Rust?** Start with the [Quick Reference →](../../../docs/rust-lessons/quick-reference.md)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jackneill) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->