Re: [RFC PATCH v2 01/10] AGENTS.md: add basic AGENTS.md for QEMU

["Alex Bennée" <alex.bennee@linaro.org>]

Chao Liu <chao.liu.zevorn@gmail.com> 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 <alex.bennee@linaro.org>
>> 
>> ---
>> 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 `qemu-security@nongnu.org`.
>> +
>> +## 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