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 - Scannable checklist of all 20+ rules

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

Made a specific mistake? Check Common Footguns

Writing production code? Review Error Handling Deep Dive first

Resource Files

Quick Reference (Start Here)

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 - ~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 - ~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 - ~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 - ~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 - ~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 - ~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 - ~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

   • •Imports and code organization
   • •Tracing subscribers
   • •Avoiding duplicated logic
2. •

   Error Handling (Sections 1-2)

   • •Option handling basics
   • •When to use expect vs unwrap
3. •

   Quick Reference

   • •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 (Complete)

   • •All Option/Result patterns
   • •Path operation footguns
2. •

   Rust Patterns (NEW!)

   • •thiserror vs anyhow
   • •Input validation
   • •Ownership patterns
   • •Arc<Mutex<T>> for concurrency
   • •SQL injection prevention
   • •Testing error paths
3. •

   File I/O Safety

   • •Atomic writes
   • •Safe file operations
   • •Testing file I/O
4. •

   Type Safety

   • •Constants → Enums progression
   • •Validation patterns
   • •User-friendly errors
5. •

   Common Footguns

   • •TOCTOU races
   • •Borrow checker patterns

Goal: Write robust, safe production code

Path 3: Advanced (Performance & Safety)

For optimizing critical code paths:

1. •

   Performance

   • •Loop optimizations
   • •Zero-copy abstractions
   • •Profiling techniques
2. •

   Common Footguns

   • •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 - 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

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:

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:

#[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:

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 - Complete guide for adding lessons

Quick steps:

1. •Add to appropriate deep-dive guide
2. •Update 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 - Start here
• •📚 All Deep-Dive Guides - Comprehensive learning
• •🔍 Common Footguns - Avoid mistakes
• •📖 Navigation Guide - Full documentation index

Ready to write better Rust? Start with the Quick Reference →