rust-guide
/rust-guide
Rust guardrails, patterns, and best practices for AI-assisted development. Use when working with Rust files (.rs), Cargo.toml, or when the user mentions Rust. Provides ownership conventions, error handling with Result/Option, testing standards, and unsafe code guidelines.
- Author
- ar4mirez ↗
- Repository
- samuel ↗
- Licence
- MIT
- Last repository change
- 29.04.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 9
No signals detected. Repository changed on 29.04.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Rust guardrails, patterns, and best practices for AI-assisted development. Use when working with Rust files (.rs), Cargo.toml, or when the user mentions Rust. Provides ownership conventions, error handling with Result/Option, testing standards, and unsafe code guidelines.
Original author description
Rust guardrails, patterns, and best practices for AI-assisted development. Use when working with Rust files (.rs), Cargo.toml, or when the user mentions Rust. Provides ownership conventions, error handling with Result/Option, testing standards, and unsafe code guidelines.
How it works
- Core Principles
- Guardrails
- Project Structure
- Error Handling Patterns
- Testing
- Tooling
- Advanced Topics
- External References
SKILL.md preview
---
name: rust-guide
description: |
Rust guardrails, patterns, and best practices for AI-assisted development.
Use when working with Rust files (.rs), Cargo.toml, or when the user mentions Rust.
Provides ownership conventions, error handling with Result/Option, testing standards,
and unsafe code guidelines.
license: MIT
metadata:
author: samuel
version: "1.0"
category: language
language: rust
extensions: ".rs"
---
# Rust Guide
> Applies to: Rust 2021 edition+, Systems Programming, CLIs, WebAssembly, APIs
## Core Principles
1. **Ownership Clarity**: Every value has one owner; borrowing is explicit and intentional
2. **Result Over Panic**: Return `Result<T, E>` for all fallible operations; `panic!` is a bug
3. **Zero-Cost Abstractions**: Use iterators, generics, and traits without runtime overhead
4. **Minimal Unsafe**: Default to `#[forbid(unsafe_code)]`; justify every `unsafe` block in writing
5. **Clippy Compliance**: All code passes `cargo clippy -- -D warnings` with zero exceptions
## Guardrails
### Edition & Toolchain
- Use Rust 2021 edition (`edition = "2021"` in Cargo.toml)
- Set `rust-version` (MSRV) in Cargo.toml for all published crates
- Use stable toolchain unless a nightly feature is explicitly justified
- Pin dependency versions with `~` for compatible updates in libraries
- Commit `Cargo.lock` for binaries; omit for libraries
- Run `cargo update` weekly for security patches
### Code Style
- Run `cargo fmt` before every commit (no exceptions)
- Run `cargo clippy -- -D warnings` before every commit
- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- `snake_case` for functions, variables, modules, crate names
- `PascalCase` for types, traits, enums, type parameters
- `SCREAMING_SNAKE_CASE` for constants and statics
- Prefer exhaustive `match` over `if let` chains
- No `use super::*` in non-test modules (explicit imports only)
- Derive order: `Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize`
### Error Handling
- Return `Result<T, E>` for all operations that can fail
- Use `thiserror` for library error types, `anyhow` for application code
- Never use `String` as an error type (create enums or use `thiserror`)
- Use `?` operator for propagation; avoid manual `match` on `Result` when `?` suffices
- `unwrap()` is forbidden outside tests and examples
- `expect("reason")` is allowed only with a comment explaining the invariant
- Use `#[must_use]` on functions returning `Result` or important values
### Lifetimes
- Let the compiler infer lifetimes whenever possible (elision rules)
- Add explicit annotations only when the compiler requires them
- Prefer owned types in structs; use references only when zero-copy is measured to matter
- Use `Cow<'a, str>` when a function may or may not allocate
- Avoid `'static` bounds unless truly needed (e.g., thread spawning, lazy statics)
### Concurrency
- Use `tokio` as the async runtime (unless project requires `async-std`)
- All async operations must have timeouts via `tokio::time::timeout`
- Use `Arc<T>` for shared ownership across threads; never `Rc<T>` in async code
- Prefer `tokio::sync::Mutex` over `std::sync::Mutex` in async contexts
- Use channels (`mpsc`, `oneshot`, `broadcast`) over shared mutable state
- Spawn tasks with `tokio::spawn`; propagate errors via `JoinHandle`
- Every `select!` branch must handle cancellation
## Project Structure
### Binary Crate
```
myproject/
├── Cargo.toml
├── Cargo.lock
├── src/
│ ├── main.rs # Entry point, minimal (parse args, call run)
│ ├── lib.rs # Public API and module declarations
│ ├── config.rs # Configuration loading
│ ├── error.rs # Custom error types
│ ├── domain/
│ │ ├── mod.rs
│ │ └── user.rs
│ └── infra/
│ ├── mod.rs
│ ├── db.rs
│ └── http.rs
├── tests/ # Integration tests
│ └── api_test.rs
├── benches/ # Benchmarks (criterion)
│ └── throughput.rs
└── examples/
└── basic_usage.rs
```
### Cargo Workspace
```
workspace/
├── Cargo.toml # [workspace] members
├── crates/
│ ├── core/ # Domain logic (no I/O)
│ │ ├── Cargo.toml
│ │ └── src/lib.rs
│ ├── api/ # HTTP layer
│ │ ├── Cargo.toml
│ │ └── src/lib.rs
│ └── cli/ # Binary entry point
│ ├── Cargo.toml
│ └── src/main.rs
└── tests/ # Workspace-level integration tests
```
- `main.rs` should be thin: parse CLI args, build config, call `lib.rs` entry
- Put all business logic in `lib.rs` modules (testable without binary)
- Use workspaces for projects with 3+ crates
- `error.rs` at crate root defines the crate-level error enum
- No global mutable state; use dependency injection via function arguments or structs
## Error Handling Patterns
### Library Errors (thiserror)
```rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum StorageError {
#[error("record {id} not found in {table}")]
NotFound { table: &'static str, id: String },
#[error("duplicate key: {0}")]
Conflict(String),
#[error(transparent)]
Database(#[from] sqlx::Error),
#[error(transparent)]
Io(#[from] std::io::Error),
}
```
### Application Errors (anyhow)
```rust
use anyhow::{bail, Context, Result};
fn load_config(path: &str) -> Result<Config> {
let raw = std::fs::read_to_string(path)
.with_context(|| format!("reading config from {path}"))?;
let config: Config = toml::from_str(&raw)
.context("parsing TOML config")?;
if config.port == 0 {
bail!("port must be non-zero");
}
Ok(config)
}
```
### Conversion With the ? Operator
```rust
// Define From impls via thiserror's #[from], then just use ?
fn create_user(db: &Pool, input: &NewUser) -> Result<User, AppError> {
validate_email(&input.email)?; // ValidationError -> AppError
let user = db.insert(input)?; // sqlx::Error -> AppError
Ok(user)
}
```
## Testing
### Unit Tests (in-module)
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_valid_email_succeeds() {
let result = Email::parse("user@example.com");
assert!(result.is_ok());
}
#[test]
fn parse_invalid_email_returns_error() {
let err = Email::parse("not-an-email").unwrap_err();
assert!(matches!(err, ValidationError::InvalidEmail(_)));
}
#[test]
fn amount_cannot_be_negative() -> Result<(), Box<dyn std::error::Error>> {
let result = Amount::new(-5);
assert!(result.is_err());
Ok(())
}
}
```
### Integration Tests (tests/ directory)
```rust
// tests/api_test.rs
use myproject::app;
#[tokio::test]
async fn health_endpoint_returns_ok() {
let app = app::build_test_app().await;
let resp = app.get("/health").await;
assert_eq!(resp.status(), 200);
}
```
### Doc Tests
```rust
/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// use mycrate::add;
/// assert_eq!(add(2, 3), 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
```
### Property-Based Testing (proptest)
```rust
use proptest::prelude::*;
proptest! {
#[test]
fn roundtrip_serialization(input in "[a-zA-Z0-9]{1,100}") {
let encoded = encode(&input);
let decoded = decode(&encoded)?;
prop_assert_eq!(input, decoded);
}
}
```
### Testing Standards
- Test names describe behavior: `fn rejected_order_cannot_be_shipped()`
- Unit tests live in `#[cfg(test)] mod tests` in the same file
- Integration tests go in `tests/` directory
- Use `#[should_panic(expected = "...")]` for panic-testing (rare)
- Use `assert!(matches!(...))` for enum variant assertions
- Coverage target: >80% for libraries, >60% for applications
- Use `cargo tarpaulin` or `cargo llvm-cov` for coverage
- Async tests use `#[tokio::test]`
## Tooling
### Essential Commands
```bash
cargo fmt # Format (non-negotiable)
cargo clippy -- -D warnings # Lint with deny
cargo test # All tests
cargo test --all-features # Test all feature combinations
cargo check # Fast type-check (no codegen)
cargo doc --open # Generate and view docs
cargo audit # Check for vulnerable deps
cargo deny check # License + advisory check
cargo bench # Run benchmarks (criterion)
```
### Cargo.toml Essentials
```toml
[package]
name = "myproject"
version = "0.1.0"
edition = "2021"
rust-version = "1.75"
[dependencies]
serde = { version = "1", features = ["derive"] }
thiserror = "2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
tracing = "0.1"
[dev-dependencies]
proptest = "1"
tokio = { version = "1", features = ["test-util"] }
[profile.release]
lto = true
codegen-units = 1
strip = true
[lints.clippy]
pedantic = { level = "warn", priority = -1 }
unwrap_used = "deny"
expect_used = "warn"
```
### Rustfmt Configuration
```toml
# rustfmt.toml
edition = "2021"
max_width = 100
use_field_init_shorthand = true
```
### MSRV Policy
- Set `rust-version` in Cargo.toml for every published crate
- Test MSRV in CI: `cargo +1.75.0 check`
- Bump MSRV only when a dependency or language feature requires it
- Document MSRV bumps in changelog
## Advanced Topics
For detailed patterns and examples, see:
- [references/patterns.md](references/patterns.md) -- Async server, builder, newtype, state machine patterns
- [references/pitfalls.md](references/pitfalls.md) -- Common ownership mistakes, lifetime traps, async gotchas
- [references/security.md](references/security.md) -- Unsafe auditing, dependency vetting, secret handling
## External References
- [The Rust Programming Language](https://doc.rust-lang.org/book/)
- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- [The Async Book](https://rust-lang.github.io/async-book/)
- [Rustonomicon (Unsafe Rust)](https://doc.rust-lang.org/nomicon/)
- [Clippy Lint Reference](https://rust-lang.github.io/rust-clippy/)
- [Error Handling in Rust (blog)](https://blog.burntsushi.net/rust-error-handling/)
- [cargo-deny](https://embarkstudios.github.io/cargo-deny/)
Files in this package (2)
- SKILL.md 10 KB
- references/patterns.md 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ar4mirez/samuel | 100 | MIT |
| buYoung/skills | 100 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 81770aee562e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100claude-skill-rust
Guide for Rust development including code style, testing, building, and quality checks using cargo tools. Apply when working with Rust code, Cargo.toml, or running cargo commands. - 100neo-rust
Use this skill when writing, refactoring, debugging, or auditing Rust code. Trigger for .rs files, Cargo projects, ownership/borrowing/lifetime issues, Result/Option error handling, unnecessary clone/performance work, unsafe code review, or modern Rust architecture. - 95rust-best-practices
Write idiomatic, robust, maintainable Rust. Use this skill whenever you write, review, refactor, debug, or explain Rust code: new crates, modules, functions, structs, traits, error types, async code, unsafe or FFI code, Cargo.toml, tests, or rustdoc. Trigger on any mention of… - 100rust
Idiomatic programming style, patterns, and conventions for Rust development. Trigger when: - Writing, refactoring, reviewing, or debugging Rust code. - Files matching the pattern **/*.rs (including Cargo.toml, Cargo.lock) are in the workspace or referenced. - Tasks involve:… - 100rust-review
Audits Rust code for unsafe blocks, ownership issues, and Cargo dependency risks. Use when reviewing Rust code or before merging Rust changes. - 90rust
This skill should be used when writing or reviewing Rust code, or when the project uses "Rust", "Cargo", "cargo clippy", "crate", or Rust module patterns. Provides Rust coding conventions, patterns, and best practices. Project-specific conventions always take priority.