nledford/engineering-review-board / skills/rust-engineering
rust-engineering
VerifiedCore Rust engineering guidance. Use when adding or changing Rust crates, modules, public APIs, domain logic, ownership and lifetime structure, traits, generics, error types, feature flags, workspaces, refactors, design patterns, or declarative/procedural macros. Do not use for checked-in hosted CI/release-provider or Docker/OCI/Compose configuration except the Rust commands they invoke; use ci-release-engineering or container-engineering. Use api-design for public service/SDK/CLI contracts, observability-engineering for telemetry/logging signal design, rust-testing-quality for test and CI lanes, rust-async-web for Tokio/Axum/Leptos work, rust-desktop-gui for native desktop GUI frameworks and delivery, rust-persistence-sql for SQLx, SeaQuery, and database adapter work, and rust-code-review for requested reviews.
Rust Engineering
Use this skill for project-neutral Rust implementation and refactoring. Keep the guidance grounded in the repository's existing architecture, toolchain, and public contracts.
MCP SDK Composition
For MCP implementation, load
mcp-server-engineering and its dated
SDK selection record.
The selection record is the canonical source for the selected Rust lane's
retrieval-time authority, package/version, tier, core-revision, transport, and
conformance caveats. It is not a target-repository pin or local test result.
MCP Rust Mechanics
Use this section only after loading
mcp-server-engineering and its dated
SDK selection record.
The parent owns MCP revision, capability, and transport rules; this section owns
Cargo, Rust API, Tokio, schema, shutdown, and test mechanics.
- Discover and resolve the crate deliberately: inspect workspace dependency
declarations,
Cargo.lock, feature flags,rust-toolchain, target support, and CI before adding or selectingrmcp. Resolve the exact crate version and enabled transport/runtime features through the repository's Cargo graph, then read that release's docs. Do not infer unqualified support, enable every feature, or add a crate merely to explore its API. - Keep service and transport adapters separate: implement the SDK's resolved
service/handler traits over typed application operations, then construct the
SDK server/client and chosen transport in
main, a dedicated adapter module, or the runtime composition root. Keep SDK sessions, transport handles, and generated request types outside domain APIs; let conversion code be explicit and small. - Use Tokio ownership and cancellation idiomatically: make task ownership
visible, propagate cancellation through owned work, retain/join spawned task
handles, and drive the selected SDK's documented
waiting()/cancel()or equivalent close path from the application shutdown owner. Never detach an SDK transport task and assume Tokio runtime drop or process exit performs orderly cleanup; confirm selected-feature and transport behavior in its docs. - Derive, then validate schemas: express handler data with concrete Rust types and the resolved SDK's supported generated-schema/derive path. Validate untrusted values at conversion boundaries and test derived/declared schemas, serialization, optional fields, and invalid nested inputs. A Rust type or generated schema does not substitute for boundary validation.
- Test the qualified adapter surface: use configured Rust test lanes and
#[tokio::test]only when the repository/runtime requires it. Unit-test transport-independent services with fakes; integration-test the resolved SDK service/transport adapter, generated schemas, cancellation, and shutdown with an SDK-supported local fixture when available. Treat conformance or real transport results as target-specific evidence, and report skipped checks.
Workflow
- Inspect the local shape first:
Cargo.toml, workspace members, crate boundaries, feature flags,rust-toolchain, CI recipes, README/AGENTS docs, and nearby modules. Use local code navigation, direct reads, and search for symbols, references, implementations, exact strings, docs, config, logs, fixtures, generated assets, and macro-generated surprises; use repository commands for tests, builds, and other validation. - State the behavior or domain change in concrete terms. Use BDD-style examples for user-visible behavior and DDD language for boundaries, invariants, and aggregate-like rules.
- Choose the smallest crate/module/API boundary that can own the behavior.
Keep framework, database, and transport concerns outside core domain logic
unless the crate is explicitly an adapter. Load
hexagonal-architecturefor ports/adapters and external actors,clean-architecturefor use-case and interface-adapter boundaries, oronion-architecturefor domain/application rings. - Design the API before filling in code: visibility, ownership, lifetimes, trait bounds, error type, feature gating, and caller obligations.
- Implement in small steps. Prefer clear safe Rust, narrow mutation, explicit invariants, and tests close to the behavior.
- Refactor after tests pass: simplify ownership, collapse accidental abstraction, remove duplicated conversions, and make invalid states harder to express.
- Verify with the repository recipe or an appropriately scoped Cargo lane.
Use ci-release-engineering for hosted
pipeline and automated release configuration, and
container-engineering for Dockerfile, OCI
image, and Compose behavior. Keep Cargo build and packaging mechanics here.
Core Rust Checklist
- Ownership expresses real responsibility. Use
&T,&mut T, owned values,Cow,Rc, orArcdeliberately; do not add clones to satisfy the compiler without checking allocation, aliasing, and lifetime implications. - Lifetimes describe relationships already present in the data model. Avoid over-generalized lifetimes, self-referential structures, and references stored where owned values would simplify the design.
- Traits and generics buy reuse, substitution, or testability. Keep bounds close to the item that needs them and avoid generic APIs when one concrete type is the honest contract.
- Error handling distinguishes caller errors, domain errors, I/O failures, and programmer bugs. Library-like crates should expose typed errors; application edges may add context and convert to user-facing responses.
- Keep core domain APIs synchronous unless the domain behavior itself requires asynchrony. Push async I/O, Tokio runtime details, channels, and task handles to application services, ports, adapters, or process wiring.
- Modules reveal boundaries. Public modules should be stable enough for callers; private modules can optimize for clarity and local cohesion.
- Collections and iterators match the semantics: ordering, uniqueness, lookup cost, allocation, and borrowing behavior should be intentional.
- Smart pointers have a reason:
Boxfor indirection or trait objects,Rcfor single-threaded sharing,Arcfor cross-thread sharing,Mutex/RwLockfor mutation behind sharing, andPinonly when pinning invariants matter. unsafeis isolated, justified, documented with safety invariants, and tested with risk-appropriate tools.
Project Setup
- Prefer one crate until independent release, feature, dependency, or compile boundaries justify a workspace member.
- Use workspace dependencies and lints when they reduce drift. Do not introduce workspace-wide policy for a local experiment.
- Feature flags should be additive. Keep defaults intentional, avoid mutually exclusive features unless the crate already has a clear policy, and test the feature combinations CI claims to support.
- Keep dependencies narrow. Inspect direct and transitive impact with
cargo treebefore adding broad crates for small needs. - Put generated code, build scripts, FFI bindings, examples, benches, and tests in conventional locations unless the repository already documents otherwise.
Desktop GUI Routing
Use rust-desktop-gui when Rust work primarily
changes a native desktop GUI framework, widget tree, event loop, window lifecycle,
platform integration, or desktop bundle requirements. This skill retains Cargo,
ownership, types, errors, workspace, and dependency mechanics. Before adding or
changing a desktop framework dependency, inspect its resolved version, features,
renderer or backend, native prerequisites, assets, and supported OS targets; use
dependency-supply-chain-review
when dependency provenance, native crates, build scripts, or installers matter.
Useful inspection commands:
cargo metadata --no-deps
cargo tree -p <package>
cargo check -p <package> --all-targets
cargo fmt
Pattern Routing
- Load
rust-design-patternswhen the Rust change needs a deliberate pattern choice: newtypes, enums, builders, RAII guards, traits as ports, compose-structs, contained unsafe modules, custom traits for complex bounds, or macros. - Load
rust-antipatternswhen reviewing or refactoring generated-code smells: clone-to-satisfy-borrow-checker, reflexiveArc<Mutex<_>>, deref polymorphism, panic at trust boundaries, async overuse, framework leakage, or brittle Rust tests.
Local CPU Parallelism Routing
Compose with parallelism-engineering
when a local CPU-bound Rust workload needs data or task decomposition, partition
sizing, bounded executor design, deterministic reduction, cancellation, or
nested-parallelism control. That skill owns the cross-language parallel design;
this skill owns Rust ownership, thread/task API, crate, and test mechanics.
Do not route ordinary Tokio, async I/O, channels, request concurrency, or
event-loop/runtime behavior to parallelism-engineering; use
rust-async-web when that async/runtime surface is
primary. Spark/PySpark execution remains with
data-platform-engineering, not local
parallelism engineering.
WebAssembly Routing
Compose with webassembly-engineering
when Rust work includes a general WebAssembly decision: a WAT or .wasm
artifact, WASI or WIT, the Component Model, host/guest contract, runtime or
target selection, capability grants, or Wasm packaging and deployment. That
skill owns those Wasm boundary and compatibility decisions. This skill retains
Rust source, Cargo, compiler and target mechanics, wasm-bindgen and generated
Rust binding mechanics, and Rust tests; the Wasm skill does not establish Rust
toolchain, target, or binding-generator support. Keep Leptos and other Rust web
framework mechanics with rust-async-web.
API and Observability Routing
- Load
api-designwhen Rust changes define or alter a public service, SDK, CLI, serialization, error, pagination, webhook/event, or generated-client contract. Keep this skill focused on ownership, types, modules, and implementation mechanics. - Load
observability-engineeringwhen Rust changes add or change durable logs, metrics, traces, request/correlation IDs, instrumentation fields, or operator-facing diagnostics.
Security Review Routing
Load security-review when Rust changes touch
implemented auth or session handling, crypto/randomness, credentials, secrets or
.env, filesystem paths, command/process execution, unsafe, FFI, plugin
boundaries, HTTP clients, SQL binding, or other trust boundaries. Use
dependency-supply-chain-review
for Cargo dependency bumps, Cargo.lock churn, build.rs, proc macros, native
crates, toolchain/bootstrap pins, provenance, or advisory questions. Use
threat-modeling before or during new auth,
service-to-service, FFI/plugin, unsafe, external-client, or sensitive data-flow
boundaries. Pair security-sensitive reviews with
security-review-evidence for sanitized
logs, telemetry, build artifacts, dependency reports, or test output.
Refactoring Guidance
- Protect current behavior first with focused tests, characterization tests, or BDD-style acceptance criteria.
- Separate mechanical moves from semantic changes when possible.
- Decide whether the refactor is defensive or simplifying. Add types and adapters to protect real invariants; delete indirection when it only forwards parameters or preserves obsolete paths.
- Move code toward domain language: named value types, explicit state transitions, and constructors that enforce invariants.
- Simplify ownership by changing data flow before adding lifetimes, reference cycles, or interior mutability.
- Simplify errors by removing duplicate variants, preserving actionable context, and keeping conversion points near adapter boundaries.
- Replace groups of mutually exclusive
Option<T>fields with enums when only one mode is valid. - Remove dead feature flags completely: call sites,
cfgs, conditional return types, monitoring scaffolding, docs, tests, and dependency gates. - Move tests with code during module splits, and keep intermediate states compiling.
- For performance refactors, measure or reproduce the bottleneck before changing algorithms, allocation patterns, locking, or async task structure.
Macros
- Prefer functions, traits, derives, builders, or generics before macros.
- Use
macro_rules!for small syntax/repetition patterns with predictable expansion. Keep patterns minimal and diagnostics readable. - Use procedural macros only when compile-time code generation materially improves the caller experience. Keep parsing, validation, and generated code covered by tests.
- Review macro hygiene, spans, error messages, generated visibility, feature gates, and compile-time cost.
- Test caller-facing macro behavior with ordinary tests, doctests,
compile_failexamples, or a compile-test harness when the failure mode is a type-system contract.
Common Crate Guidance
serde/serde_json: keep serialization formats explicit at API, storage, and message boundaries. Use derives for stable data shapes, custom serializers only when the wire contract requires them, and tests for compatibility-sensitive JSON.anyhow: appropriate at application edges, CLIs, and task orchestration where context matters more than typed recovery. Library-like crates and domain APIs should expose typed errors callers can handle.tokio: userust-async-webfor runtime, task, cancellation, backpressure, Axum, and Leptos details. Introduce async deliberately for I/O-bound or high-concurrency work; do not hide blocking work inside async functions.reqwest: keep HTTP clients at adapter boundaries, configure timeouts, handle status codes deliberately, avoid logging secrets, and test request/response mapping without real network calls when practical.randand ID crates: userandom-data-identifiersfor secure randomness, deterministic seeds, UUIDs, and collision-resistant identifiers.
Anti-Patterns
- Fighting borrow errors by cloning, leaking, boxing, or adding
Arc<Mutex<_>>before revisiting ownership. - Adding abstractions because they are common in other languages rather than because this code has multiple real implementations.
- Exposing framework, SQL, HTTP, or serialization types from core domain APIs without a deliberate adapter boundary.
- Making feature flags subtractive or environment-sensitive.
- Treating Clippy suggestions, design patterns, or public docs as substitutes for behavior tests and explicit contracts.
Acceptance Criteria
Successful Rust engineering work has:
- a clear behavior or domain reason for the change;
- crate/module/API boundaries that match repository conventions;
- ownership, lifetimes, traits, errors, and features chosen intentionally;
- tests or examples covering the changed behavior or invariant;
- relevant Cargo verification run or a clear explanation of what could not run.
TypeScript Zod Interoperability
For a real TypeScript/backend JSON crossing, load zod-engineering. Rust retains native validation, DTO/domain conversion, stable serialization/errors, and shared-fixture parity.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |