Rust
Overview
Rust is a systems programming language focused on safety, concurrency, and performance. The ownership system guarantees memory safety without garbage collection, and the type system enforces thread safety at compile time.
When to use: Systems programming, web services (axum), CLI tools (clap), terminal UIs (ratatui), WebAssembly, performance-critical applications, anything requiring memory safety without runtime overhead.
When NOT to use: Rapid prototyping where compile times matter more than safety, simple scripting tasks, projects where the team has no Rust experience and deadlines are tight.
Quick Reference
| Pattern |
API / Tool |
Key Points |
| Ownership transfer |
let b = a; |
a is moved, no longer usable |
| Borrowing |
&T / &mut T |
One mutable OR many immutable refs |
| Lifetime annotation |
fn f<'a>(x: &'a str) -> &'a str |
Ties output lifetime to input |
| Error propagation |
? operator |
Converts and propagates errors |
| Custom errors |
thiserror::Error derive |
Structured error types with Display |
| Ad-hoc errors |
anyhow::Result<T> |
Context chaining for applications |
| Async runtime |
#[tokio::main] |
Entry point for async programs |
| Spawn task |
tokio::spawn(async { }) |
Concurrent async task execution |
| HTTP router |
axum::Router::new().route(...) |
Composable routing with extractors |
| Extractors |
Json<T>, Path<T>, State<T> |
Type-safe request parsing |
| Serialization |
#[derive(Serialize, Deserialize)] |
serde with format-agnostic derives |
| CLI parsing |
#[derive(Parser)] |
clap derive API for arg parsing |
| TUI rendering |
terminal.draw(|f| { }) |
Immediate-mode ratatui rendering |
| Benchmarking |
criterion::Criterion |
Statistical benchmarking framework |
| Dep auditing |
cargo deny check |
License, vulnerability, source audit |
| Binary release |
cargo dist init |
Cross-platform binary distribution |
| Changelog |
release-plz update |
Auto semver bump and changelog |
Common Mistakes
| Mistake |
Correct Pattern |
| Returning reference to local variable |
Return owned type or use lifetime parameter |
Using unwrap() in library code |
Return Result and let caller decide |
clone() to satisfy borrow checker |
Restructure code to avoid the borrow conflict |
| Blocking in async context |
Use tokio::task::spawn_blocking |
| Shared mutable state without sync |
Use Arc<Mutex<T>> or channels |
String where &str suffices |
Accept &str in function parameters |
Ignoring must_use warnings |
Handle or explicitly discard with let _ = |
| Large enum variants |
Box the large variant to reduce overall size |
async fn in traits without bounds |
Add Send bound or use async-trait crate |
Missing #[tokio::test] on async tests |
Use #[tokio::test] instead of #[test] |
Delegation
- Code exploration: Use
Explore agent
- Architecture review: Use
Task agent
- Code review: Delegate to
code-reviewer agent
If the docker skill is available, delegate multi-stage container build patterns to it.
If the github-actions skill is available, delegate CI pipeline configuration to it.
If the openapi skill is available, delegate API specification and code generation to it.
References
- Ownership, borrowing, lifetimes, and type system patterns
- Error handling with Result, Option, thiserror, and anyhow
- Async programming with Tokio runtime and concurrency
- Web APIs and backends with axum, tower, and sqlx
- Terminal user interfaces with ratatui and crossterm
- CLI applications with clap, config, and signal handling
- Testing patterns and criterion benchmarking
- Release pipeline with cargo-deny, cargo-dist, and release-plz
1---2name: rust3description: Rust language patterns and ecosystem covering ownership, borrowing, lifetimes, error handling (Result/Option, thiserror, anyhow), async with Tokio, traits, generics, serde serialization, Cargo workspaces, and testing. Includes axum web framework, ratatui terminal UI, clap CLI parsing, criterion benchmarking, cargo-deny supply chain security, cargo-dist binary distribution, and release-plz changelog automation. Use when writing Rust code, designing ownership models, building async services with Tokio/axum, creating terminal UIs with ratatui, setting up CLI applications with clap, configuring CI/CD pipelines for Rust, benchmarking with criterion, auditing dependencies with cargo-deny, or distributing binaries with cargo-dist.4license: MIT5---6
7# Rust
8
9## Overview
10
11Rust is a systems programming language focused on safety, concurrency, and performance. The ownership system guarantees memory safety without garbage collection, and the type system enforces thread safety at compile time.
12
13**When to use:** Systems programming, web services (axum), CLI tools (clap), terminal UIs (ratatui), WebAssembly, performance-critical applications, anything requiring memory safety without runtime overhead.
14
15**When NOT to use:** Rapid prototyping where compile times matter more than safety, simple scripting tasks, projects where the team has no Rust experience and deadlines are tight.
16
17## Quick Reference
18
19| Pattern | API / Tool | Key Points |
20| ------------------- | ----------------------------------- | ------------------------------------ |
21| Ownership transfer | `let b = a;` | `a` is moved, no longer usable |
22| Borrowing | `&T` / `&mut T` | One mutable OR many immutable refs |
23| Lifetime annotation | `fn f<'a>(x: &'a str) -> &'a str` | Ties output lifetime to input |
24| Error propagation | `?` operator | Converts and propagates errors |
25| Custom errors | `thiserror::Error` derive | Structured error types with Display |
26| Ad-hoc errors | `anyhow::Result<T>` | Context chaining for applications |
27| Async runtime | `#[tokio::main]` | Entry point for async programs |
28| Spawn task | `tokio::spawn(async { })` | Concurrent async task execution |
29| HTTP router | `axum::Router::new().route(...)` | Composable routing with extractors |
30| Extractors | `Json<T>`, `Path<T>`, `State<T>` | Type-safe request parsing |
31| Serialization | `#[derive(Serialize, Deserialize)]` | serde with format-agnostic derives |
32| CLI parsing | `#[derive(Parser)]` | clap derive API for arg parsing |
33| TUI rendering | `terminal.draw(\|f\| { })` | Immediate-mode ratatui rendering |
34| Benchmarking | `criterion::Criterion` | Statistical benchmarking framework |
35| Dep auditing | `cargo deny check` | License, vulnerability, source audit |
36| Binary release | `cargo dist init` | Cross-platform binary distribution |
37| Changelog | `release-plz update` | Auto semver bump and changelog |
38
39## Common Mistakes
40
41| Mistake | Correct Pattern |
42| --------------------------------------- | --------------------------------------------- |
43| Returning reference to local variable | Return owned type or use lifetime parameter |
44| Using `unwrap()` in library code | Return `Result` and let caller decide |
45| `clone()` to satisfy borrow checker | Restructure code to avoid the borrow conflict |
46| Blocking in async context | Use `tokio::task::spawn_blocking` |
47| Shared mutable state without sync | Use `Arc<Mutex<T>>` or channels |
48| `String` where `&str` suffices | Accept `&str` in function parameters |
49| Ignoring `must_use` warnings | Handle or explicitly discard with `let _ =` |
50| Large enum variants | Box the large variant to reduce overall size |
51| `async fn` in traits without bounds | Add `Send` bound or use `async-trait` crate |
52| Missing `#[tokio::test]` on async tests | Use `#[tokio::test]` instead of `#[test]` |
53
54## Delegation
55
56- **Code exploration**: Use `Explore` agent
57- **Architecture review**: Use `Task` agent
58- **Code review**: Delegate to `code-reviewer` agent
59
60> If the `docker` skill is available, delegate multi-stage container build patterns to it.
61> If the `github-actions` skill is available, delegate CI pipeline configuration to it.
62> If the `openapi` skill is available, delegate API specification and code generation to it.
63
64## References
65
66- [Ownership, borrowing, lifetimes, and type system patterns](references/ownership-and-types.md)
67- [Error handling with Result, Option, thiserror, and anyhow](references/error-handling.md)
68- [Async programming with Tokio runtime and concurrency](references/async-tokio.md)
69- [Web APIs and backends with axum, tower, and sqlx](references/axum-web.md)
70- [Terminal user interfaces with ratatui and crossterm](references/ratatui-tui.md)
71- [CLI applications with clap, config, and signal handling](references/cli-applications.md)
72- [Testing patterns and criterion benchmarking](references/testing-and-benchmarks.md)
73- [Release pipeline with cargo-deny, cargo-dist, and release-plz](references/release-pipeline.md)
oakoss