From cde761a90d7b2fd9f9bda52f646c0034e2f0a541 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Fri, 8 May 2026 21:40:15 +0200 Subject: [PATCH] misc: add AGENTS.md for easier LLM use Initial attempt for a lightweight AGENTS.md to improve working with LLMs on this repository and avoid common pitfalls. Assisted-by: Codex:GPT-5.5 Signed-off-by: Philipp Schuster --- AGENTS.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..94ad27733 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,81 @@ +## For Humans + +This is a compact [AGENTS.md](https://agents.md/) file for Cloud Hypervisor. +It is meant to help automated coding agents make useful changes that stay safe, +reviewable, and compatible with the project's normal engineering constraints. + +## For LLMs + +### Project Context + +- Start with `README.md` for the project shape and `CONTRIBUTING.md` for the + contribution rules, coding style, commit message guidance, and LLM assistance + disclosure policy. Following `CONTRIBUTING.md` is crucial! +- The main supported architectures are `x86_64` and `aarch64`; the main + hypervisor backends are KVM and MSHV. `x86_64` with KVM gets the most regular + exercise, but changes must not make the other first-class targets worse. + +### Change Guidelines + +- Prefer correctness, safety, and readability over micro-optimizations. Keep + changes small, reviewable, and aligned with the existing crate/module + boundaries. Avoid speculative changes and unrelated refactoring. +- For API, config, migration, device model, or hypervisor boundary changes, + consider the effect on all architectures and all backends. Changes to one + backend can be okay if the other backend still functions properly and could + be extended or modified later. +- Follow Rust best practices and the style already present in the touched code. +- Avoid new dependencies unless the benefit is clear and local alternatives are + not enough. +- Preserve existing behavior unless the requested change explicitly needs a + behavior change; refactors must preserve behavior. Call out compatibility or + migration implications. +- Do not invent APIs, behavior, or requirements. If something is uncertain, + state the uncertainty and proceed only with minimal, explicit assumptions. + +### Safety and Domain Notes + +- Prefer safe Rust. If `unsafe` is necessary, keep it narrow, add a `SAFETY:` + comment with the invariants, and make sure the surrounding code upholds them. +- Assume concurrency matters. Avoid races, unsynchronized shared state, and + implicit ordering assumptions; prefer clear ownership and synchronization. +- Keep docs and comments short and useful. Document non-trivial invariants at + struct definitions and critical state transitions. +- Logging should be minimal and high signal. Use `info!` for important normal + state changes that matter in production; use `warn!` or `error!` only for + abnormal conditions. Keep `debug!` for focused diagnostics. + +### Build and Test Notes + +- Some workspace members require the `kvm` feature to build or test correctly. + When a default build failure looks feature-related, retry the narrow command + with `--features kvm` before widening the diagnosis. +- Prefer narrow crate/test commands while iterating, then broaden verification + when the touched surface justifies it. +- Formatting currently needs nightly-only rustfmt features; use + `cargo +nightly fmt --all`. +- Add targeted unit tests for bug fixes and non-trivial logic where practical. + Keep test scaffolding minimal and focused. +- Integration tests live in `./cloud-hypervisor/tests/` and are normally driven + by `./scripts/dev_cli.sh` / `./scripts/run_integration_tests_*.sh`. They need + host privileges, workloads, and container setup. To build the integration-test + code directly without the infrastructure from `./scripts`, set the Rust cfg + `devcli_testenv` or simply build through `clippy` which automatically includes + these code paths; otherwise the integration-test code is not included. Do not + assume the tests can be run directly in a restricted agent environment; ask + the developer to run them when real integration coverage is needed. + +### Commit and Patch Formatting + +- Follow the rules in `CONTRIBUTING.md`, including reviewable commit structure, + valid component prefixes, 72-column commit messages, and a `Signed-off-by` + trailer. +- Lines in a commit message that are allowed to exceed the 72-column limit are + specified in `./scripts/gitlint/rules`. +- For LLM-assisted changes, follow the disclosure guidance in `CONTRIBUTING.md`: + use the project's `Assisted-by:` trailer when disclosure is needed, and do not + add `Co-authored-by` or similar trailers unless that policy changes. +- Temporary allowances such as `#[allow(unused)]` or ignored tests are only + acceptable if resolved within the same commit series or paired with a clear + TODO referencing a ticket. Ask the developer if in doubt. +