devs:rust-core

What this skill does

# Rust Core Development

Comprehensive guidance for Rust development across web, CLI, desktop, AI/LLM applications, and systems programming.

## Quick Reference Guide

### By Task Type

**Getting Started**
- **New Project Setup**: Use `scripts/init_rust_project.sh` to scaffold a project with best practices
- **Core Principles**: See [references/principles.md](references/principles.md) for ownership, borrowing, and Rust fundamentals
- **Common Errors**: See [references/common-errors.md](references/common-errors.md) for solutions to frequent compiler errors

**Writing Code**
- **Design Patterns**: Consult [references/patterns.md](references/patterns.md) for builder, newtype, RAII, and other patterns
- **Error Handling**: See [references/error-handling.md](references/error-handling.md) for Result, Option, anyhow, and thiserror
- **Async Programming**: See [references/async-patterns.md](references/async-patterns.md) for Tokio, channels, and concurrency

**Domain-Specific Development**
- **Web APIs**: See [references/web-frameworks.md](references/web-frameworks.md) for Axum, Actix-web, and Rocket
- **AI/LLM**: See [references/ai-llm.md](references/ai-llm.md) for OpenAI, Anthropic, Ollama, and RAG
- **CLI Tools**: See [references/cli-tui.md](references/cli-tui.md) for Clap and Ratatui
- **Desktop Apps**: See [references/desktop-tauri.md](references/desktop-tauri.md) for Tauri
- **Logging**: See [references/logging-observability.md](references/logging-observability.md) for tracing and metrics

**Code Quality**
- **Testing**: See [references/testing.md](references/testing.md) for unit, integration, and property-based testing
- **Code Review**: See [references/code-review.md](references/code-review.md) for review checklist and anti-patterns
- **Performance**: See [references/performance.md](references/performance.md) for profiling and optimization

**Project Management**
- **Dependencies**: See [references/dependencies.md](references/dependencies.md) for Cargo.toml best practices
- **Project Structure**: See [references/project-structure.md](references/project-structure.md) for modules and workspaces
- **Essential Crates**: See [references/crates-core.md](references/crates-core.md) for commonly used libraries

### By Question Type

| Question | Reference |
|----------|-----------|
| "How do I handle errors?" | [error-handling.md](references/error-handling.md) |
| "Which web framework should I use?" | [web-frameworks.md](references/web-frameworks.md) |
| "How do I work with async/await?" | [async-patterns.md](references/async-patterns.md) |
| "How do I integrate OpenAI/Claude?" | [ai-llm.md](references/ai-llm.md) |
| "How do I build a CLI?" | [cli-tui.md](references/cli-tui.md) |
| "How do I create a desktop app?" | [desktop-tauri.md](references/desktop-tauri.md) |
| "Why won't this compile?" | [common-errors.md](references/common-errors.md) |
| "How do I improve performance?" | [performance.md](references/performance.md) |
| "How do I add logging?" | [logging-observability.md](references/logging-observability.md) |
| "How should I name this?" | [naming.md](references/naming.md) |
| "What are best practices?" | [principles.md](references/principles.md) |
| "How do I test this?" | [testing.md](references/testing.md) |

## Core Workflows

### 1. Starting a New Project

1. **Initialize Project**
   ```bash
   ./scripts/init_rust_project.sh my-project
   ```

2. **Set Up Development Tools**
   - Configure linting: Copy `assets/configs/clippy.toml` and `assets/configs/rustfmt.toml`
   - Configure security: Copy `assets/configs/deny.toml`
   - Run audit: `./scripts/audit_dependencies.sh`

3. **Add Logging**
   ```bash
   ./scripts/setup_logging.sh
   ```

4. **Choose Architecture**
   - **Web API**: Consult [web-frameworks.md](references/web-frameworks.md) for Axum, Actix-web, or Rocket
   - **CLI Tool**: See [cli-tui.md](references/cli-tui.md) for Clap
   - **Desktop App**: See [desktop-tauri.md](references/desktop-tauri.md)
   - **Library**: See [project-structure.md](references/project-structure.md)

### 2. Implementing Features

1. **Design First**
   - Review [principles.md](references/principles.md) for ownership and type-driven design
   - Check [patterns.md](references/patterns.md) for applicable design patterns
   - Plan error handling strategy from [error-handling.md](references/error-handling.md)

2. **Write Code**
   - Follow naming conventions from [naming.md](references/naming.md)
   - Use appropriate patterns and error handling
   - Add tracing/logging as you go

3. **Test**
   - Write unit tests (see [testing.md](references/testing.md))
   - Add integration tests for public APIs
   - Consider property-based tests for complex logic

### 3. Code Review and Refinement

1. **Self-Review**
   - Run through [code-review.md](references/code-review.md) checklist
   - Check for common anti-patterns
   - Verify error handling

2. **Performance Check**
   - Profile if performance-critical (see [performance.md](references/performance.md))
   - Benchmark changes with Criterion
   - Avoid premature optimization

3. **Security Audit**
   ```bash
   ./scripts/audit_dependencies.sh
   ```

## Decision Guides

### Choosing a Web Framework

**Use Axum when:**
- Building modern REST/GraphQL APIs
- Want composable middleware (Tower ecosystem)
- Prefer type-driven extractors
- Building microservices

**Use Actix-web when:**
- Need maximum performance
- Building high-throughput APIs
- Want mature, battle-tested framework
- Familiar with actor model

**Use Rocket when:**
- Rapid prototyping
- Want batteries-included features
- Smaller team or learning Rust web
- Traditional web application

See [web-frameworks.md](references/web-frameworks.md) for detailed comparison and code examples.

### Error Handling Strategy

**Use `anyhow` for:**
- Applications (binaries)
- Quick prototyping
- Internal tools
- When you need ergonomic error handling with context

**Use `thiserror` for:**
- Libraries (public APIs)
- When consumers need to handle specific error cases
- Type-safe error hierarchies
- Production code with well-defined error types

See [error-handling.md](references/error-handling.md) for patterns and examples.

### When to Use Async

**Use async/await when:**
- I/O-bound operations (network, file system)
- Web servers handling many concurrent requests
- Database connection pooling
- Working with streams of data

**Don't use async when:**
- CPU-bound operations (use `spawn_blocking` instead)
- Simple CLI tools
- Performance isn't critical
- Complexity isn't justified

See [async-patterns.md](references/async-patterns.md) for Tokio patterns and best practices.

## Automation Scripts

### Available Scripts

**`scripts/init_rust_project.sh`**
Initialize a new Rust project with best practices:
- Common dependencies (anyhow, thiserror, serde, tracing)
- Benchmark setup with Criterion
- Optimized release profile
- Proper .gitignore

Usage: `./scripts/init_rust_project.sh my-project [bin|lib]`

**`scripts/audit_dependencies.sh`**
Audit dependencies for security and licensing:
- Runs cargo-audit for security vulnerabilities
- Runs cargo-deny for license compliance
- Shows outdated dependencies

Usage: `./scripts/audit_dependencies.sh`

**`scripts/setup_logging.sh`**
Set up tracing-based logging:
- Adds tracing dependencies
- Creates logging module with JSON support
- Provides initialization code

Usage: `./scripts/setup_logging.sh`

## Configuration Templates

### `assets/configs/clippy.toml`
Clippy linting configuration for strict code quality

### `assets/configs/rustfmt.toml`
Code formatting configuration (100 char width, Unix newlines)

### `assets/configs/deny.toml`
cargo-deny configuration for:
- Security advisory checking
- License compliance (MIT, Apache-2.0, BSD allowed)
- Duplicate dependency detection
- Source verification

## Reference Documentation

All reference files provide in-depth guidance on specific topics:

### Core Language
- **[principles.md](references/pr