writing-rust

description	Idiomatic Rust development. Use when writing Rust code, Cargo crates/workspaces, Rust tests, or rustfmt/clippy/cargo workflows. Emphasizes ownership, Result errors, small APIs, stdlib-first dependencies, fast cargo feedback, and behavior tests. NOT for Go, Python, TypeScript, shell scripts, or infra-only work.
name	writing-rust

Rust Development

Use only for Rust crates and Cargo workspaces. Follow the crate's edition, MSRV, toolchain file, CI, and local style. Rust CLI development (clap, argument parsing, subcommands) is in scope; apply patterns.md and testing.md — there is no dedicated CLI reference.

Read First

Read principles.md before writing, changing, or reviewing Rust code. Read conditional references only when the change touches that area.

Conditional References

• patterns.md — crate layout, modules, ownership, traits, errors, async, unsafe, and public APIs.
• testing.md — adding or reshaping Rust tests; keep the local test loop fast.
• linting.md — changing rustfmt, Clippy, cargo check, CI gates, or slow lint workflows.

Comments and Rustdoc

• Use /// or //! rustdoc for public APIs when users need contracts, edge cases, examples, or safety notes.
• Add implementation comments only for non-obvious constraints, invariants, side effects, tradeoffs, or unsafe assumptions.
• Keep comments short. Move longer rationale to docs, issue links, or design notes.
• Do not comment obvious code or restate names and types.