writing-rust git:20260627.a4cca8dB

Immutable. This exact content is served forever at /api/v1/blob/ed692801ceb04258.

---
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.

## Read First

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

## Conditional References

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

## Edition and MSRV

- Inspect `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml`, CI, and nearby code before using edition- or version-specific APIs.
- Do not use APIs newer than `package.rust-version` or the pinned toolchain unless the task is an upgrade.
- Use Edition 2024 syntax only when the crate already opts into `edition = "2024"`.
- Respect feature flags. Do not enable `--all-features` assumptions in code unless incompatible feature combinations are ruled out.

## Verification

Run focused Cargo checks while editing, then the project-configured build, tests,
format, and lint before final output. Prefer:

```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
```

Use `cargo nextest run` when the project already uses nextest. Run `cargo test --doc` separately when doctests matter because nextest does not run doctests.

If a check is unavailable, state that and run the closest configured gate. If a check fails, quote the failure, diagnose the cause, fix one issue, and rerun the relevant check.

## Failure Cases

- No clear Rust root: locate `Cargo.toml` before choosing files, package names, or commands.
- Unknown MSRV or edition: inspect manifests, toolchain files, CI, and lockfiles before using newer syntax or APIs.
- New crate requested: confirm stdlib or existing crates cannot meet the requirement.
- `unsafe` needed: isolate it, document the safety invariant, and add focused tests or run configured Miri checks.
- Broad or risky edit: state the risk and ask before acting. Do not run destructive commands.

## Final Response

Include:

- changed files
- checks run and results
- checks skipped with reasons
- remaining risks or follow-ups