Rust Development

Workflow

For any non-trivial Rust change:

1. Discover project guidelines — Read CLAUDE.md, AGENTS.md (in repo root and .claude/, .cursor/, .codex/ subdirs), rustfmt.toml, clippy.toml, .clippy.toml, deny.toml, and [workspace.lints] / [lints] sections in Cargo.toml. These rules apply in addition to Core Rules below.

2. Implement — Delegate to rust-dev:rust-coder agent. It rediscovers guidelines, implements, then verifies its own work with cargo clippy --workspace --tests -- -D warnings and cargo test --workspace before reporting done.

3. Review — Invoke rust-dev:review-rust-code agent after rust-coder completes. This is mandatory, not optional. Convert findings into TODOs: critical/warning → fix; suggestions → triage.

4. Fix issues one by one — Delegate each fix to rust-dev:rust-coder. Do not batch unrelated fixes into one delegation.

5. Final build — cargo build --workspace (or delegate to rust-dev:rust-builder).

Core Rules

1. Edition 2024: Always edition = "2024" in Cargo.toml
2. FAIL FAST: Every error MUST propagate with ? or return Err. Logging is NOT handling. See error-handling.md
3. Dependency versions: Use x.x format (e.g., serde = "1.0"). Find latest with python3 scripts/check_crate_version.py <crate>
4. Workspace architecture: Root Cargo.toml defines workspace only. Separate crates for lib/cli/client
5. Error types: thiserror (with backtrace) for libraries, anyhow for binaries/tests
6. CLI-first config: Never bypass CLI args. Use from_cli_args(), never Default that reads env
7. No env::set_var in tests: Pass config through function parameters
8. Async: Use tokio consistently
9. Visibility: Private (default) > pub(crate) > pub
10. No magic numbers: Use const or CLI args

Adding Dependencies

1. Run python3 scripts/check_crate_version.py <crate-name> to find latest version
2. Add to [workspace.dependencies] in root Cargo.toml with x.x format
3. Reference in member crates: serde = { workspace = true }

Common deps: thiserror = "2.0", anyhow = "1.0", tokio = { version = "1", features = ["full"] }, serde = { version = "1.0", features = ["derive"] }, clap = { version = "4.5", features = ["derive"] }

Creating New Projects

Use the template in assets/workspace-template/:

project/
├── Cargo.toml              # Workspace root, no code
├── project/                # Library crate (thiserror)
│   ├── Cargo.toml
│   └── src/lib.rs
└── project-cli/            # Binary crate (anyhow + clap)
    ├── Cargo.toml
    └── src/main.rs

Module Organization

Split modules when file exceeds ~500 lines or tests take 50%+ of file. See module-organization.md for patterns.

Error Handling

The most critical standard. See error-handling.md for full rules and examples.

Quick check: If you see if let Err or match ... Err without return Err or ?, it's a bug.

References

• error-handling.md — FAIL FAST rules, thiserror/anyhow patterns, error chain preservation
• module-organization.md — When/how to split modules, test extraction
• dependency-guide.md — Workspace deps, feature flags, common crates

Scripts

• scripts/check_crate_version.py — Query crates.io for latest dependency versions