rust-style

Files (7)

• SKILL.md
• api-design.md · references/
• implementation.md · references/
• safety-concurrency.md · references/
• testing.md · references/
• tokio.md · references/
• wire-and-persistence.md · references/

SKILL.md (first lines)

# Rust Style

If this plugin is not initialized or an Agent IX command fails, read [the dev-tools setup guide](https://github.com/agent-ix/dev-tools/blob/main/setup.md) for its prerequisites and local diagnosis.

Load this skill before designing, writing, or reviewing Rust. These are Agent IX
defaults for Rust code, not instructions for a particular repository. Read
`AGENTS.md`, `CLAUDE.md`, a repository Rust skill, and its lint and formatter
configuration too. More specific repository instructions take precedence. A
documented rule remains authoritative even if existing code violates it. Treat
the rule as superseded only when a newer explicit project authority changes it;
report the conflict when those authorities disagree.

## Core rules to keep in context

- Borrow immutable inputs as `&str`, `&Path`, `&[T]`, or `&T` where possible.
  Prefer unique ownership and borrowing over unnecessary deep clones or shared
  ownership. Use identity newtypes when two IDs could be confused.
- Use `Option` for genuine absence, `Result` for recoverable failures, and a
  distinct typed condition for each failure a caller must distinguish. Each
  crate that surfaces errors uses a stable `Copy` code enum and a `thiserror`
  envelope; never branch on human-readable error text.
- Keep public APIs deliberate: document every `pub` item, avoid accidental
  visibility, use standard traits when they fit, and consider compatibility
  before exposing enum variants, struct fields, or a `const fn`.
- Prefer direct, auditable control flow. Match closed enums exhaustively; do
  not map an unknown variant to a valid but wrong value. Use an iterator
  operation or a `for` loop according to which makes the behavior clearer.
- Return an error for bad caller-controlled data. Do not let malformed input
  trigger `unwrap`, indexing, slicing, or arithmetic panics. An invariant
  panic is only appropriate when the repository permits it and the invariant
  is explicit. Prefer pattern matching to check-then-`unwrap`.
- Default to `#![forbid(unsafe_code)]` and workspace safety lints. An allowed
  unsafe operation requires a `SAFETY:` comment, an explanation of why safe
  code is insufficient, and an audit of the surrounding abstraction.
- Use typed wire payloads and reject unknown fields on every deserialized
  payload. Keep secrets out of input types. At wire and persistence
  boundaries, use checked integer conversions rather than a bare narrowing
  `as` cast.
- Write deterministic tests that exercise real behavior. In a repository that
  traces tests to requirements, bind each new test with `/// Trace:` or its
  declared trace attribute; do not hand-edit a Test Matrix. Use the
  repository's required gates and license header.

## Read the applicable detailed rules

- [API design](references/api-design.md): public or cross-crate APIs, types,
  constructors, traits, ownership, and documentation.
- [Implementation](references/implementation.md): modules, imports, naming,
  control flow, formatting, macros, and ordinary Rust code.
- [Safety and concurrency](references/safety-concurrency.md): panic paths,
  unsafe, locks, cancellation, resource bounds, and concurrent state.
- [Wire and persistence](references/wire-and-persistence.md): errors,
  deserialization, IPC, external input, persisted values, and conversions.
- [Testing](references/testing.md): unit and integration tests, doubles,
  trace tags, external services, and deterministic assertions.
- [Tokio](references/tokio.md): Tokio tasks, blocking work, runtime context,
  and sync-over-async bridges. Read this only when Tokio is used.

These rules describe code and review decisions. Enforceable gates such as
Clippy, cargo-deny, and unsafe audits belong in the repository's CI and lint
configuration; follow that configuration when it is stricter.

From agent-ix/dev-tools, MIT.

More from agent-ix/dev-tools