Home › Rust › Rust library crate AGENTS.md

Rust library crate AGENTS.md

AGENTS.md for publishable Rust library crates: API design, error types, features, MSRV, docs, and semver checks.

AGENTS.mdRust

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Rust library crate

## Commands
`cargo build` · `cargo test --all-features` · `cargo clippy --all-targets --all-features -- -D warnings` · `cargo fmt --check` · `cargo doc --no-deps` · `cargo semver-checks` (before releases)

## API design
- Keep the public surface small and intentional; re-export from `lib.rs`. Mark exhaustive-looking enums/structs `#[non_exhaustive]` if they may grow.
- Accept generic, borrowed inputs (`impl AsRef<Path>`, `&str`, `impl IntoIterator`) and return owned, concrete types.
- Errors: a crate `Error` enum with `thiserror`; implement `std::error::Error` and keep sources. Don't expose `anyhow` in public APIs, and never panic on bad input; `unwrap` only on proven invariants with a comment.
- Builders for types with many optional settings.
- Implement common traits where they make sense: `Debug`, `Clone`, `PartialEq`, `Default`, `Display`, `serde` behind a `serde` feature.

## Crate hygiene
- `#![warn(missing_docs)]`; every public item has rustdoc with an example that compiles as a doc test.
- Optional dependencies behind features; default features minimal. Features must be additive.
- Declare `rust-version` (MSRV) in `Cargo.toml` and don't use newer std APIs without bumping it.
- No `unsafe` unless necessary; each block gets a `// SAFETY:` comment.
- Update `CHANGELOG.md` for user-visible changes.

## Never
Run `cargo publish` or bump the major version without approval.