On this page

On this page

Rust Toolchain

Mandate

TypeScript and Python are the default languages for AI-assisted development. Rust is not a default choice — use it only when the project genuinely needs:

  • Maximum performance with memory safety
  • Systems components
  • Native extensions for other languages
  • WebAssembly targets

Adopting Rust requires explicit justification and user approval, recorded in a project ADR.

Familiarity with Rust is not a justification on its own.

Scope

This document sets the baseline standard for Rust projects; it does not replace project-level evaluation. Before choosing Rust, confirm two things: the project matches one of the cases above, and TypeScript, Python, or Go cannot meet the requirement at reasonable cost.

Version Policy

Use the stable toolchain, installed through mise or rustup.

Use edition 2024 in Cargo.toml.

Do not enable nightly features by default; a nightly requirement is an explicit, recorded decision.

Usage Rules

Build and Packaging

Use cargo as the only build and package tool.

Do not hide standard cargo commands behind custom build scripts.

Formatting

Use rustfmt for formatting.

Expose cargo fmt through mise tasks.

Linting

Use cargo clippy for linting.

CI must treat warnings as errors:

cargo clippy --all-targets -- -D warnings

unsafe Blocks

Every unsafe block requires a // SAFETY: comment stating the invariant that makes the block sound.

Do not use unsafe to work around the borrow checker.

Error Handling

Use thiserror for library error types.

Use anyhow only at binary boundaries; do not leak it through public library APIs.

Workspace Layout

Use a cargo workspace for multi-crate projects.

Keep dependency versions synchronized at the workspace level.

Testing

Run cargo test in CI.

Works with

  • mise — versioning: the Rust toolchain and related tools are managed and exposed through mise tasks.
  • Quality Gates — same checks: prek and CI run the same lint and format configuration.
  • Git Workflow — commit discipline: Rust changes follow the standard commit and PR rules.
  • Testing Strategy — test focus: what to verify, and at which level.