agentharness rust.instructions.md

Generated from languages/rust/CONVENTIONS.md by tools/generate-copilot-instructions.sh (https://github.com/andr-ca/agentharness) — do not hand-edit; regenerate instead. Only applied by Copilot when editing a file matching *.rs.

---

Rust Conventions & Best Practices

Naming (snake_case for functions/variables/modules, PascalCase for types/traits/enum-variants, SCREAMING_SNAKE_CASE for consts/statics), module layout, and the borrow-checker mechanics are all standard Rust community convention — see the Rust API Guidelines and RFC 430 naming for the parts not worth restating here. rustfmt (formatting) and clippy (lints) are the non-negotiable baseline — run both in CI; don't hand-argue formatting. Below are the places this repo makes an actual decision.

unwrap()/expect() is a rigor-tier decision, not a habit

.unwrap() and .expect() turn a None/Err into a panic. That's fine at the Prototype tier and in tests, but at the Internal and Production tiers library and request-path code must propagate errors with ? instead — a panic in a request handler takes down more than the request. Reserve expect() for genuine invariants that cannot fail, and when you use it, make the message state why it can't fail, not what failed:

// Good: the message documents the invariant.
let port = env::var("PORT").expect("PORT is set by the launcher before exec");

// Bad in Internal/Production code: propagate instead.
let config = load_config()?; // not load_config().unwrap()

See .github/CODING_GUIDELINES.md's rigor tiers for which tier applies.

Error types: thiserror for libraries, anyhow for binaries

• Libraries expose a concrete, matchable error enum (#[derive(thiserror::Error)]) so callers can handle specific cases — don't leak Box<dyn Error> across a public API.
• Binaries / application code can use anyhow::Result with .context() to add human-readable context at each boundary, since the top-level handler only needs to report, not match.