Rust Expert

Rust Expert

Use this as the default Rust engineering router. Inspect the repo first, load only the references needed for the task, then use compiler/test feedback as design evidence.

Operating Model

1. Read the local guidance and manifests first: AGENTS.md, Cargo.toml, Cargo.lock, rust-toolchain.toml, .cargo/config.toml, CI, justfile, mise.toml, and nearby tests. 2. Classify the task before editing: compile failure, implementation, review, refactor, dependency, public API, release, performance, or security. 3. Fix the root cause. Avoid silencing Rust with reflexive .clone(), Arc<Mutex<_>>, broad trait bounds, unwrap, or unsafe. 4. Use repo-native gates first. When command surface is unclear, run scripts/discover-rust-gates.mjs <repo-root>. 5. Research current docs/source when facts can drift: dependency additions or upgrades, version-sensitive APIs, Tauri/plugin support, public API/release decisions, security, unsafe/FFI, or novel crates.

Domain Routing

Use these implicit specialist skills when the task clearly belongs there:

If no specialist owns the task, stay in rust-expert.

Reference Map

Load the smallest needed set:

• references/toolchain-cargo.md: editions, MSRV, resolver, lockfiles, features,

workspace policy, verification commands.

• references/ownership-async-errors.md: borrow checker, ownership,

lifetimes, async Send, task ownership, typed errors.

• references/crate-selection.md: preferred crates, dependency decision rules,

feature hygiene, source-refresh triggers.

• references/testing-quality.md: unit/integration/doctest/property/snapshot/

benchmark checks and reviewable test design.

• references/performance-security.md: measurement, allocations, unsafe/FFI,

supply chain, cargo-deny/audit, secrets and subprocesses.

Toolchain Policy

Existing repos: preserve detected contracts first. Do not change edition, resolver, rust-version, lockfile policy, or exact toolchain pins unless the task is explicitly a migration or the repo is missing required metadata.

Greenfield defaults:

• edition = "2024".
• Set [workspace] resolver = "3" explicitly for virtual workspaces.
• Add an explicit rust-version and document the policy.
• Commit Cargo.lock by default; for public libraries, also test latest

dependency resolution because consumers use Cargo.toml.

• Avoid exact rust-toolchain.toml version pins unless reproducibility,

nightly, embedded/custom targets, or release policy requires them.

Verification Ladder

Start narrow, then broaden:

cargo check -p <crate>
cargo test -p <crate> <test_name>
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-targets --all-features --locked
cargo test --doc --workspace --locked

Use cargo nextest run when configured. Add cargo hack, cargo deny, cargo audit, cargo semver-checks, or release tooling only when the repo or change surface warrants it.

Helper Scripts

• scripts/discover-rust-gates.mjs [repo-root]: print likely Rust gates.
• scripts/check-reference-links.mjs <skill-dir...>: validate local skill links.
• scripts/check-trigger-evals.mjs <skill-dir...>: validate trigger eval JSON.

Crate Selection

Use existing repo choices first. Add or replace dependencies only when the benefit exceeds API, maintenance, compile-time, feature, license, and supply chain cost.

Research Order

1. Inspect manifests, lockfile, features, MSRV, and current dependency graph. 2. Check official docs and examples for current API shape. 3. Check source/changelog/release notes when behavior or version risk matters. 4. Inspect transitive features with cargo tree -e features. 5. Prefer one canonical crate per capability; remove parallel stacks when doing a deliberate hard cut.

Opinionated Defaults

Anti-Patterns

Freshness Triggers

Research live docs/source before relying on:

• new dependencies or major upgrades;
• Tauri plugin/platform support;
• Clap/Ratatui/Tauri current APIs;
• security-sensitive crates;
• MSRV-sensitive dependencies;
• release automation or public API compatibility;
• crates with low maintenance signals or unclear licenses.

Ownership, Async, And Errors

Use this reference when the task involves borrow checker errors, lifetimes, mutability, async Send failures, task lifecycle, error boundaries, or recovery behavior.

Borrow Checker Repair Order

1. Reproduce the exact compiler diagnostic. 2. Read the owning type, caller, and intended invariant. 3. Narrow borrow scopes before changing types. 4. Move behavior onto the owner when mutation authority belongs there. 5. Split data structures when independent fields are being borrowed together. 6. Borrow or move deliberately; clone only when shared ownership or retained values are semantically required.

Avoid:

• .clone() just to silence E0382.
• Arc<Mutex<_>> as a generic Send/Sync fix.
• RefCell where ordinary ownership works.
• Public fields that let callers violate invariants.
• unsafe to bypass ownership errors.

Async Design

Ask what kind of work this is:

Rules:

• Do not block the executor with blocking I/O, sleeps, or CPU-heavy loops.
• Do not hold lock guards, borrowed refs, or non-Send values across .await

unless the architecture explicitly supports it.

• Prefer bounded channels for backpressure.
• Use JoinSet or owned task groups for related spawned work.
• Use tokio::select! for cancellation, shutdown, timeouts, and races.
• Treat dropped channels as expected shutdown signals when appropriate.

Error Boundaries

Do not use anyhow to erase errors that drive retry behavior, CLI exit codes, JSON contracts, public APIs, or operator remediation.

Recovery Rules

• Invalid input: no retry; return an actionable error.
• Timeout, 503, rate limit: bounded retry with backoff and jitter.
• Invalid config: fail fast.
• Data corruption: stop and surface high-severity error.
• Dependency unavailable: timeout/circuit/fallback only if product semantics

allow degraded behavior.

Performance, Unsafe, And Security

Use this reference when performance, unsafe, FFI, supply chain, secrets, subprocesses, paths, parsing, or untrusted input are in scope.

Performance Order

1. Measure in release mode. 2. Check algorithm and data structure first. 3. Inspect allocation and clone patterns. 4. Check I/O batching and lock contention. 5. Add parallelism/SIMD/unsafe only after identifying a real hotspot.

Useful tools:

cargo bench
cargo flamegraph --bin <binary>
heaptrack ./target/release/<binary>
cargo bloat --release --bin <binary>
cargo tree -e features

Avoid optimizing debug builds, hiding algorithmic problems with parallelism, or adding unsafe for micro-optimizations without proof.

Unsafe Rules

Every unsafe block or item needs:

• a SAFETY: comment explaining caller obligations and why they hold;
• the smallest possible unsafe scope;
• a safe abstraction around the boundary when possible;
• checks for aliasing, lifetimes, initialization, alignment, thread-safety, and

panic behavior;

• Miri, sanitizer, fuzzing, or targeted tests when risk warrants it.

FFI Rules

• Confirm ABI and repr(C) layout.
• Document ownership transfer and allocation/freeing side.
• Validate nullability before dereference.
• Do not unwind across FFI.
• Convert raw pointers at the boundary.
• Make cleanup explicit when it can fail.

Supply Chain

Prefer maintained crates with clear license, docs, source, CI, and recent activity. Run configured policy tools:

cargo deny check
cargo audit
cargo tree -d
cargo machete

Use cargo-udeps only when nightly is acceptable. Treat build scripts and proc macros as higher-risk code in sensitive environments.

Application Security

Pay extra attention to:

• auth and authorization checks;
• crypto;
• parsers and deserialization of untrusted data;
• filesystem paths and archive extraction;
• subprocess arguments and shell execution;
• network timeouts and TLS;
• secrets in logs/errors;
• temporary files and permissions.

Testing And Quality

Use this reference when adding tests, changing contracts, reviewing quality, or closing out Rust work.

Test Choice

Test Quality Rules

• Name tests by behavior.
• Keep fixtures small and deterministic.
• Test failure paths when introducing a new failure class.
• Do not weaken tests to fit the implementation.
• Assert stable contracts, not full debug strings.
• Avoid sleeping in async tests; use barriers, fake clocks, or explicit

notifications.

• For snapshots, review and redact unstable fields.
• For mocks, test the boundary contract instead of duplicating internals.

Review Checklist

For Rust reviews, findings lead:

• correctness and data loss;
• public API and serialization contracts;
• async lifecycle, cancellation, and backpressure;
• error classification and user/operator messages;
• dependency and feature changes;
• unsafe/FFI invariants;
• test coverage for changed risk.

Report file/line evidence, impact, and a concrete fix direction.

Closeout Commands

Prefer repo-native commands. Common Rust closeout:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-targets --all-features --locked
cargo test --doc --workspace --locked
git diff --check

Use narrower commands while iterating; broaden before claiming completion.

Toolchain And Cargo

Use this reference for toolchain policy, workspace structure, feature hygiene, dependency resolution, and verification commands.

Existing Repo Policy

Preserve these contracts unless the user explicitly asks for a migration:

• edition
• rust-version
• workspace resolver
• rust-toolchain.toml
• .cargo/config.toml
• lockfile policy
• CI matrix and README MSRV policy

Changing any of these can affect dependency resolution and user compatibility. Treat edition/resolver/MSRV changes as migrations with lockfile review and full repo checks.

Greenfield Defaults

Use these defaults for new Rust projects unless the target domain says otherwise:

[package]
edition = "2024"
rust-version = "1.85"

For virtual workspaces:

[workspace]
resolver = "3"
members = ["crates/*"]

Use rust-version = "1.85" as the Rust 2024 compatibility floor for reusable libraries/tools, then raise it only for chosen APIs/dependencies. For internal apps, current stable is acceptable if documented and CI tracks it.

Lockfiles

Commit Cargo.lock by default for apps, CLIs, services, workspaces, and agent tooling. For published libraries, committing the lockfile is acceptable, but CI should also test latest dependency resolution because downstream users are not bound by the library lockfile.

Avoid upper-bounding dependencies to preserve old Rust compatibility unless a real incompatibility requires it. Prefer rust-version plus resolver 3 and latest-dependency CI.

Features

• Use workspace dependency ownership when possible.
• Keep features additive.
• Disable default features only when you know what stack you are removing.
• Avoid full feature sets unless the task genuinely needs the entire surface.
• Test important feature combinations with cargo hack when public crates or

optional stacks are involved.

Useful commands:

cargo metadata --format-version=1
cargo tree -e features
cargo tree -d
cargo hack check --feature-powerset --no-dev-deps

Verification Tiers

Focused iteration:

cargo check -p <crate>
cargo test -p <crate> <test_name>

Normal closeout:

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

Public API/release:

cargo test --doc --workspace --locked
cargo semver-checks
release-plz update --dry-run

Supply-chain/security:

cargo deny check
cargo audit

Use repo-native wrappers (just, mise, make, xtask, RTK) when they exist.