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/