rust-conventions

name: rust-conventions description: >- Rust house style for subctl-adjacent work — cargo, clippy, rustfmt, error handling with thiserror / anyhow, async patterns with tokio, testing.

Load this skill whenever a worker is touching .rs files. Subctl has a Rust component (the policy bash-gate kernel) and several adjacent projects use Rust for performance-sensitive paths. These are the defaults to apply when the project's local CLAUDE.md doesn't override. scope: dev-team loaded_by_default: [] created_at: "2026-05-10" created_by: operator

Rust Conventions

Default ecosystem skill for Rust-flavored work. The subctl policy gate's performance-critical path was rewritten in Go; for any new performance work where Go isn't a fit, Rust is the default. Argent-core's "rust spine" and several adjacent agents (argent-core-rust-spine) are also Rust.

1. Tooling — cargo, clippy, rustfmt

Everything goes through cargo. No raw rustc.

cargo new --bin my-tool      # new binary crate
cargo new --lib my-lib       # new library crate
cargo build                  # debug build
cargo build --release        # release build
cargo run -- arg1 arg2       # run with args
cargo test                   # tests
cargo clippy -- -D warnings  # lint with warnings as errors
cargo fmt                    # format
cargo fmt --check            # check formatting without modifying

Pre-commit checks

The standard pre-commit gate for any Rust commit:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

If any of these fail, fix before committing. Don't disable clippy lints without justification; #[allow(...)] annotations require a one-line comment explaining why.

2. Edition and toolchain

Target Rust edition 2021 (2024 once stabilized in the operator's toolchain). Pin the toolchain explicitly:

# rust-toolchain.toml
[toolchain]
channel = "1.83.0"          # whatever's current stable; pin, don't float
components = ["rustfmt", "clippy"]

Don't use nightly unless a specific feature requires it; if you must, isolate nightly-only code behind a feature flag.

3. Cargo.toml hygiene

[package]
name = "my-tool"
version = "0.1.0"
edition = "2021"
rust-version = "1.83"
license = "MIT"

[dependencies]
anyhow = "1"
thiserror = "1"
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[dev-dependencies]
assert_fs = "1"
proptest = "1"

• Pin major versions ("1") for libraries; pin minor versions ("1.83") for the toolchain
• Group [dependencies] and [dev-dependencies]; alphabetize within
• Use features = [...] instead of default-features = false + re-enabling unless you specifically need to trim
• One workspace per project; multiple crates under members = [...] for large projects

4. Error handling — thiserror for libs, anyhow for apps

Library crate: define typed errors with thiserror.

use thiserror::Error;

#[derive(Debug, Error)]
pub enum ResolveError {
    #[error("backend unavailable: {0}")]
    BackendUnavailable(String),

    #[error("invalid key: {key}")]
    InvalidKey { key: String },

    #[error("io: {0}")]
    Io(#[from] std::io::Error),
}

pub type Result<T> = std::result::Result<T, ResolveError>;

Binary crate / app glue: use anyhow::Result<T> at the top level.

use anyhow::{Context, Result};

fn main() -> Result<()> {
    let cfg = load_config().context("loading config")?;
    run(cfg)?;
    Ok(())
}

The .context("...") calls form a breadcrumb trail when errors propagate. Use them liberally — they're free at runtime and priceless when debugging.

Never unwrap() or expect() in production paths

unwrap and expect are acceptable in:

• Tests
• Examples
• Initialization code that genuinely cannot fail (and you can prove it)

Everywhere else: propagate with ? or handle explicitly. expect("infallible") is a smell — if it's infallible, encode that in the type.

5. Async — tokio

When async is needed, tokio is the default runtime. Multi-threaded scheduler for general work; current-thread for CLI utilities.

#[tokio::main]
async fn main() -> Result<()> {
    let client = reqwest::Client::new();
    let results = futures::future::join_all(
        urls.iter().map(|u| client.get(u).send())
    ).await;
    Ok(())
}

• One runtime per binary; never block_on from inside an async context
• tokio::select! for racing operations
• tokio::time::timeout for bounded waits — bare .await with no timeout is a smell on any external call
• Drop guards: structured concurrency via scopes (tokio::task::spawn + explicit JoinHandle::abort on shutdown) — no orphaned tasks

For non-async crates, prefer sync code. Don't drag tokio in for the sake of "future-proofing."

6. Module structure

src/
  lib.rs              # public surface, re-exports
  config.rs           # one module per concept
  secrets/
    mod.rs            # module entry, re-exports
    backends.rs       # implementation details
    audit.rs
  bin/
    cli.rs            # binary entrypoint
tests/
  integration.rs      # cross-module tests

• One concept per module, not one type per file
• pub use re-exports in lib.rs / mod.rs define the crate's public surface
• Internal modules (pub(crate)) for things shared across the crate but not part of the public API

7. Naming

8. Logging — tracing, not log

use tracing::{info, warn, error, instrument};

#[instrument(skip(client))]
async fn resolve(client: &Client, key: &str) -> Result<String> {
    info!(key = %key, "resolving secret");
    let value = client.get(key).await
        .map_err(|e| { warn!(error = %e, "backend failed"); e })?;
    Ok(value)
}

• tracing over log — structured fields, spans, async-aware
• Use info!, warn!, error! — debug! and trace! for noise that's off by default
• Configure subscriber at the binary entrypoint, never in library code
• Same [scope] prefix convention if logs route through subctl: info!(target: "secrets", "resolved {}", key)

Sensitive values never appear in logs. Use tracing::field::Empty and fill selectively, or annotate with skip(...) on #[instrument].

9. Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn returns_env_var_when_set() {
        std::env::set_var("MY_KEY", "value");
        assert_eq!(resolve_secret("my_key").unwrap(), "value");
    }

    #[tokio::test]
    async fn async_path_works() {
        let result = fetch_one("http://localhost").await;
        assert!(result.is_err());
    }
}

• Unit tests in #[cfg(test)] mod tests next to the code
• Integration tests in tests/*.rs — one file per scenario
• #[tokio::test] for async tests; vanilla #[test] for sync
• assert!, assert_eq!, assert_ne! — unwrap on Result is fine in tests
• Property-based tests via proptest for anything with non-trivial input space

10. Unsafe

Almost never. If you write unsafe:

1. Block with a // SAFETY: ... comment explaining the invariant
2. The unsafe block contains the smallest scope possible
3. The function's public signature is safe — invariants verified inside

If you can't write the SAFETY comment, you don't understand the unsafe well enough to write it. Reach for the safe alternative.

11. Common crates (operator defaults)

If a project already uses different crates, match its choices. Don't migrate as a side effect.

12. Commit messages

Conventional commits, same shape as the Node and Python sides:

feat(policy): bash-gate kernel cold-start under 5ms
fix(audit): rotate JSONL when size exceeds threshold
refactor(secrets): extract backend trait

13. What this skill does NOT cover

• Embedded / no_std development
• WASM targets — separate concern
• Project-specific layout (subctl policy kernel vs argent rust-spine) — read the project's CLAUDE.md
• Node — node-conventions
• Python — python-conventions