# AGENTS.md — Rust API Guidelines

Idiomatic public-API design for Rust crates, per the official Rust API Guidelines.

- Casing per RFC 430: `UpperCamelCase` types/traits/variants, `snake_case`
  fns/modules/macros, `SCREAMING_SNAKE_CASE` consts; acronyms are one word (`Uuid`).
- Getters omit `get_` (`fn name(&self)`); reserve `get` for the obvious single accessor.
- Conversions by cost: `as_*` free borrow, `to_*` expensive, `into_*` consuming.
- Iterators are `iter` / `iter_mut` / `into_iter` returning `Iter` / `IterMut` / `IntoIter`.
- Derive common traits eagerly: `Debug`, `Clone`, `Copy`, `PartialEq`/`Eq`,
  `PartialOrd`/`Ord`, `Hash`, `Default`; add `Display` for human output.
- Conversions use `From` / `TryFrom` / `AsRef` / `AsMut`; never hand-write `Into`/`TryInto`.
- Collections implement `FromIterator` + `Extend`; gate Serde behind a `serde` feature.
- Keep types `Send + Sync` where possible; generic I/O takes `R: Read` / `W: Write` by value.
- Error types implement `std::error::Error` + `Send + Sync + 'static`.
- `Drop` never panics or blocks; offer `close()`/`flush()` -> `Result` for fallible teardown.
- Use newtypes for static distinctions; use enums/structs over bare `bool`/`Option` args.
- Flag sets use the `bitflags` crate, not enums; complex constructors get a builder.
- Validate arguments — make invalid states unrepresentable, else return `Result`.
- Keep struct fields private; seal traits not meant for downstream impl.
- Use `#[non_exhaustive]` on extensible enums/structs; don't duplicate derived bounds on the struct.
- Document `# Errors` / `# Panics` / `# Safety`; rustdoc examples use `?`, not `unwrap`.
- Feature names have no placeholders (`std`, not `use-std`); crate names avoid `-rs`/`-rust`.
- Source: https://rust-lang.github.io/api-guidelines/