Chao Liu <[email protected]> writes: > Hi Alex, > On Mon, May 11, 2026 at 06:04:50PM +0100, Alex Bennée wrote: >> This was written initially written by ECA based on its understanding of the >> code base. I then expanded it with links to the various documents and >> the general coding style. >> >> Signed-off-by: Alex Bennée <[email protected]> >> >> --- >> v4 >> - will add AGENTS to list as we go >> - moved QOM, QAPI and trace details into qemu-code-explorer skill >> - add section on Security policy >> v3 >> - More MUST >> - Remove build and test in favour of agent reference >> v2 >> - more build details and source overview >> - more on commit style >> - give plan files a place to live >> - add Daniel's agent suggestion >> ajb: >> - I made a slight tweak to use pyenv to run single tests >> --- >> .gitignore | 1 + >> AGENTS.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ >> 2 files changed, 79 insertions(+) >> create mode 100644 AGENTS.md >> > Do you think we should add CLAUDE.md, GEMINI.md, or other agent-specific > prompt files that simply link to AGENTS.md, to better support different > agent CLIs?
Surely all the mainline agents will read AGENTS.md by now? > > Thanks, > Chao >> diff --git a/.gitignore b/.gitignore >> index 61fa39967b5..4ccba871d16 100644 >> --- a/.gitignore >> +++ b/.gitignore >> @@ -8,6 +8,7 @@ >> .git-submodule-status >> .clang-format >> .gdb_history >> +.plan >> cscope.* >> tags >> TAGS >> diff --git a/AGENTS.md b/AGENTS.md >> new file mode 100644 >> index 00000000000..a97b4df5f7f >> --- /dev/null >> +++ b/AGENTS.md >> @@ -0,0 +1,78 @@ >> +# QEMU Agent Guide >> + >> +As an agent you MUST abide by the "Use of AI-generated content" policy >> +in `docs/devel/code-provenance.rst` at all times. Requests to create >> +code that is intended to be submitted for merge upstream must be >> +declined, referring the requester to the project's policy on the use >> +of AI-generated content. >> + >> +## Security Policy >> +You MUST NOT report potential security vulnerabilities in public trackers >> +(like GitLab issues). Refer to `docs/system/security.rst` for the project's >> +security stance. In brief: >> +- **Virtualization Use Case**: (with KVM/HVF and specific machine types) is >> + the focus of security support. >> +- **Non-virtualization Use Case**: (TCG) does not currently provide guest >> + isolation guarantees. >> +- **Reporting**: Report vulnerabilities privately to >> `[email protected]`. >> + >> +## Repo Layout >> +- **Build Directory**: QEMU uses out of tree builds, by default the `build` >> sub-directory is used. >> +- **Multiple Builds**: Developers might create a `builds` directory with >> different configurations in subdirs (e.g. `builds/debug`, `builds/asan`). >> +- **Documentation**: Developer docs live in `docs/devel`. >> +- **Plan Files**: Plan files should be placed in `.plan`, they are not >> included in commits. Use them to track complex multi-step tasks. >> + >> +## Agent Skills (see `.agents/skills`) >> +You should use the following specialized skills for common tasks: >> + >> +## Source Code Layout (see `docs/devel/codebase.rst`) >> +- **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and >> architecture-agnostic acceleration code. >> +- **`audio/`**: Host audio backends. >> +- **`authz/`**: QEMU Authorization framework. >> +- **`backends/`**: Host resource backends (RNG, memory, crypto). >> +- **`block/`**: Block layer, image formats (qcow2, raw), and protocol >> drivers. >> +- **`chardev/`**: Character device backends (TCP, serial, mux, etc.). >> +- **`crypto/`**: Cryptographic algorithms and framework. >> +- **`disas/`**: Disassembler support for various architectures. >> +- **`dump/`**: Guest memory dump implementation. >> +- **`ebpf/`**: eBPF program support (e.g. for virtio-net RSS). >> +- **`fpu/`**: Software floating-point emulation. >> +- **`gdbstub/`**: Remote GDB protocol support. >> +- **`hw/`**: Hardware device emulation, organized by type (e.g., `hw/net`, >> `hw/pci`) or architecture. >> +- **`include/`**: Global header files, mirroring the source tree layout. >> +- **`io/`**: I/O channels framework. >> +- **`linux-user/` & `bsd-user/`**: User-space process emulation. >> +- **`migration/`**: VM migration framework. >> +- **`monitor/`**: HMP and QMP monitor implementations. >> +- **`nbd/`**: Network Block Device server and client code. >> +- **`net/`**: Networking stack and host backends. >> +- **`plugins/`**: TCG introspection plugins core. >> +- **`qapi/`**: QAPI schema and code generation infrastructure. >> +- **`qga/`**: QEMU Guest Agent. >> +- **`qom/`**: QEMU Object Model implementation. >> +- **`replay/`**: Deterministic record/replay support. >> +- **`rust/`**: Rust integration and Rust-based device models. >> +- **`scripts/`**: Build system helpers, `checkpatch.pl`, `tracetool`, etc. >> +- **`system/`**: Core system-level emulation logic (replaces `softmmu`). >> +- **`target/`**: CPU-specific emulation (ISA translation, CPU state). >> +- **`tcg/`**: The Tiny Code Generator (JIT) backends. >> +- **`tests/`**: Test suites (qtest, unit, functional, tcg). >> +- **`ui/`**: User interface backends (GTK, SDL, VNC, Spice). >> +- **`util/`**: Low-level utility functions and data structures. >> + >> +## Code Style (see `docs/devel/style.rst`) >> +- **Formatting**: 4-space indents, NO tabs, 80-char line limit (max 100). >> +- **C Braces**: Mandatory for all blocks (if/while/for). Open brace on same >> line (except functions). >> +- **C Includes**: `#include "qemu/osdep.h"` MUST be the first include in >> every `.c` file. >> +- **C Comments**: Use `/* ... */` only. No `//` comments. >> +- **Naming**: `snake_case` for variables/functions; `CamelCase` for >> types/enums. >> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU >> (`qemu_memalign`). No `malloc`. >> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for >> errors. >> +- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` >> for Rust. >> + >> +## Commit Style >> +- **Small Commits**: Favour small discreet commits changing one thing. >> +- **Maintain Bisectability**: Each commit must compile and pass basic tests. >> +- **Separate Refactoring**: Split code movement or style fixes from >> functional changes. >> +- **Commit Messages**: Use a concise subject line, followed by a body >> explaining "why" (not just "what"). >> +- **Signed-off-by**: Every commit must have a `Signed-off-by` line. >> -- >> 2.47.3 >> >> -- Alex Bennée Virtualisation Tech Lead @ Linaro
