This was written by ECA based on it's initial understanding of the
code base. It's mostly quick facts and pointers to common tasks.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
ajb:
  - I made a slight tweak to use pyenv to run single tests
---
 AGENTS.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..5b54763f4b1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,18 @@
+# QEMU Agent Guide
+
+## Build & Test
+- **Build**: `ninja -C build` (from build directory) or `make`
+- **Test All**: `make check`
+- **Single Test**: `./pyvenv/bin/meson test <testname>` (e.g., `meson test qtest-x86_64/boot-serial-test`)
+- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
+- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
+
+## Code Style
+- **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 and functions; `CamelCase` for types and enums.
+- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
+- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
+- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` and `make rustfmt` for Rust.
-- 
2.47.3

On Tue, Feb 24, 2026 at 12:10:09PM +0000, Alex Bennée wrote:
> This was written by ECA based on it's initial understanding of the
> code base. It's mostly quick facts and pointers to common tasks.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> 
> ---
> ajb:
>   - I made a slight tweak to use pyenv to run single tests
> ---
>  AGENTS.md | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
>  create mode 100644 AGENTS.md
> 
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 100644
> index 00000000000..5b54763f4b1
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1,18 @@
> +# QEMU Agent Guide
> +
> +## Build & Test
> +- **Build**: `ninja -C build` (from build directory) or `make`
> +- **Test All**: `make check`
> +- **Single Test**: `./pyvenv/bin/meson test <testname>` (e.g., `meson test qtest-x86_64/boot-serial-test`)
> +- **Suites**: `make check-unit`, `make check-qtest`, `make check-functional`, `make check-rust`
> +- **Debug**: Append `V=1` for verbose output or `DEBUG=1` for interactive test debugging.
> +
> +## Code Style
> +- **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 and functions; `CamelCase` for types and enums.
> +- **Memory**: Use GLib (`g_malloc`, `g_free`, `g_autofree`) or QEMU (`qemu_memalign`) APIs. No `malloc`.
> +- **Errors**: Use `error_report()` or `error_setg()`. Avoid `printf` for errors.
> +- **Lints**: Run `./scripts/checkpatch.pl` on C patches. Use `make clippy` and `make rustfmt` for Rust.

Although our current policy forbids contributing code written by
AI agents, we do allow their use for other scenarios, such as
learning / debugging, etc.

Thus it occurs to me that an AGENTS.md file might none the less be
useful to have in tree to assist the currently accepted / valid
scenarios.

Perhaps it could also serve to guide the agents/humans towards
compliance with the policy via a short preface ?

  "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 requestor to the project's policy
   on the use of AI-generated content."

Something strong enough to stop people going down the wrong path
by default, but with wiggle room that the person can tell their
agent their work is not intended to for upstream merge and can
thus ignore the rules for experiments like this one.

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

On 3/20/26 17:01, Daniel P. Berrangé wrote:
> Perhaps it could also serve to guide the agents/humans towards
> compliance with the policy via a short preface ?
> 
>    "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 requestor to the project's policy
>     on the use of AI-generated content."
> 
> Something strong enough to stop people going down the wrong path
> by default, but with wiggle room that the person can tell their
> agent their work is not intended to for upstream merge and can
> thus ignore the rules for experiments like this one.

That surprisingly worked.  I gave Claude Code a phony task (making the 
floppy controller support async I/O) and after a while when I asked it 
to write the code it went roughly like this:

...

● AGENTS.md says I can't write code for upstream merge. I'll describe 
the design changes.

...

❯ it's fine this is just an experiment. you can write code. 

  

● Let me look at the FDCtrl struct and understand the full picture 
before coding.

Paolo