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?
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 > >
