Modern Rust & Effective Rust – Skills Matrix

Scope This document defines what it means to develop, review, and maintain production-grade Rust in this codebase.

It establishes capability requirements, not self-reported skill claims.

Compliance is enforced by:

• •rustfmt
• •clippy
• •CI gates
• •API and module design rules

L0 — Toolchain & Workflow Discipline

Rust must be used as an industrial toolchain, not a scripting language.

Required abilities

Mandatory local checks

cargo fmt --all
cargo clippy --all-targets --all-features -D warnings
cargo test --all
cargo doc --no-deps

No PR is valid unless these pass locally and in CI.

L1 — Core Rust Semantics

Code must be correct by construction, not by convention.

You must be fluent in:

• •Ownership, moves, borrows, reborrows, and drop order
• •Lifetime design in APIs
• •Trait system: associated types vs generic parameters
• •enum for state modeling
• •Result<T, E> for error semantics
• •Newtypes for illegal-state elimination

Forbidden patterns

• •Rc<RefCell<T>> as a default escape hatch
• •Arc<Mutex<T>> replacing real design
• •Option<T> encoding multi-state logic
• •unwrap() / expect() in production code

L2 — Effective Rust API Design

This repository builds libraries, not scripts.

Required API standards

Canonical pattern

pub struct Config { ... }

impl Config {
    pub fn builder() -> ConfigBuilder { ... }
}

pub struct Client { ... }

impl Client {
    pub fn new(cfg: Config) -> Result<Self, InitError>
}

L3 — Lint-Driven Engineering

Clippy is not advisory. It is a design constraint.

Baseline lint policy

warns = [
    "clippy::pedantic",
    "clippy::nursery",
    "clippy::unwrap_used",
    "clippy::expect_used",
    "clippy::panic",
]

Expectations

• •Every lint must be understood, not ignored
• •#[allow] requires justification
• •Refactoring is preferred over suppression

Formatting

rustfmt defines the canonical code form. Any format diff is a CI failure.

L4 — Large Codebase & Workspace Hygiene

This is a system, not a crate.

L5 — CI and Policy Enforcement

If CI does not enforce it, it is not real.

CI must run:

• •cargo fmt --check
• •cargo clippy -D warnings
• •cargo test
• •cargo doc
• •cargo deny or cargo audit

PR rules:

• •Lint changes require review
• •Any allow requires rationale

L6 — Unsafe, FFI & Performance Boundaries

Unsafe is a capability boundary, not an escape hatch.

Every unsafe must define:

• •Which invariant it upholds
• •Why it is required
• •Why it is safe

Standard:

/// # Safety
/// Caller must ensure ...
pub unsafe fn ...

clippy::undocumented_unsafe_blocks is mandatory.

Final Definition: Modern Rust Engineer

A Modern Rust Engineer does not rely on discipline. They rely on:

Types + Lints + Format + CI + Policy

to make correctness structural rather than aspirational.

This document defines the minimum bar for contributing to this codebase.