AGENTS.md template for Rust

# Project instructions

This repository is a Rust crate or Cargo workspace. Preserve crate boundaries, public APIs, feature behavior, error contracts, and the project's minimum supported Rust version when one is declared.

## Start here

- Read the nearest `Cargo.toml`, module tree, public types, feature declarations, and tests before editing.
- Use the toolchain selected by `rust-toolchain.toml` or repository documentation.
- Prefer existing crates and standard-library facilities over adding dependencies for narrow behavior.
- Preserve user changes and do not rewrite `Cargo.lock` without a dependency change in scope.

## Commands

- `cargo build --locked`: compile using the committed lockfile.
- `cargo test --locked`: run unit, integration, and documentation tests.
- `cargo fmt --all -- --check`: verify formatting.
- `cargo clippy --all-targets --all-features -- -D warnings`: run configured lint checks across targets and features.
- `cargo test --workspace --locked`: test all workspace members when this is a workspace.

Adjust flags for the repository's feature matrix, target platforms, no-std support, workspace defaults, or minimum Rust version.

## Repository map

- `src/lib.rs` and `src/main.rs`: crate roots and public module structure.
- `src/bin/`: additional binaries.
- `tests/`: black-box integration tests.
- `examples/` and documentation tests: executable usage contracts.
- Workspace member crates: independently owned APIs and dependency boundaries.

## Rust rules

- Model ownership and borrowing directly; avoid cloning, boxing, or interior mutability without a demonstrated need.
- Keep public types and trait bounds as small as possible while preserving the existing API.
- Return structured errors through the project's established error type; do not replace recoverable errors with panics.
- Keep `unsafe` code minimal, documented with invariants, and covered by tests around the safe wrapper.
- Do not suppress Clippy lints broadly. Scope any allowance and explain why the lint is not applicable.
- Preserve feature independence and test meaningful non-default feature combinations when behavior changes.

## Dependencies and compatibility

- Add dependencies only to the crate that owns the need and review default features before enabling them.
- Preserve serialization formats, FFI layout, protocol fields, and CLI behavior unless change is explicit.
- Treat lockfile policy differently for applications and libraries according to existing repository practice.
- Do not publish crates, bump versions, or modify release metadata unless requested.

## Testing and validation

- Add focused unit tests close to internal behavior and integration tests for public contracts.
- Keep documentation examples compiling when public APIs change; `cargo test` runs documentation tests by default.
- Run focused tests during iteration, then formatting, Clippy, and the full required test matrix.
- Test the affected workspace dependents when changing a shared crate.

## Definition of done

- The affected targets, tests, and documentation examples compile and pass.
- Formatting and configured Clippy checks are clean.
- Public API, features, unsafe invariants, and lockfile effects were reviewed.
- No unrelated generated files, versions, dependencies, or user changes were modified.
- The handoff lists changed crates, commands run, and remaining platform or feature risk.