Re: [RFC PATCH v3 01/11] AGENTS.md: introduce a very basic guide for AI agents

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

Peter Maydell <peter.maydell@linaro.org> writes:

> On Sat, 16 May 2026 at 11:09, Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>>
>> On 15/5/26 18:30, Alex Bennée wrote:
>> > AGENTS.md is the agent agnostic place for placing instructions for
>> > agents. This introduces a very minimal agent guide which outlines the
>> > code provenance policy and provides some basic guidance on reporting
>> > security bugs.
>> >
>> > As Gemini doesn't look at AGENTS.md even as a fallback option I've
>> > included a symlink.
>> >
>> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
>> > +## Security Policy (see `docs/system/security.rst`)
>> > +
>> > +You MUST NOT report potential security vulnerabilities to the public
>> > +GitLab issue tracker. They should be reported privately to
>> > +`qemu-security@nongnu.org`.
>> > +
>> > +**Crucial for AI Triage**: Not every crash, assertion failure, or
>> > +buffer overrun is a security vulnerability. Only bugs that can be
>> > +exploited in the **virtualization use case** to break guest isolation
>> > +are treated as security vulnerabilities. In brief these are:
>> > +- **Hardware Accelerators**: e.g. KVM, HVF and others, TCG is explicitly excluded.
>>
>> HVF isn't withing security boundary:
>> https://lore.kernel.org/qemu-devel/abAcaahy_FsBonZ7@redhat.com/
>>
>> For the "other accelerators" we should ask confirmation for respective
>> maintainers. AFAICT only KVM and Xen are expected to be secure;
>> MSHV, WHPX, nvmm and nitro didn't opted in yet (Cc'ing respective
>> maintainers).
>>
>> Wouldn't it be better to have a document describing the security code
>> boundary and have the AGENT.md refer to it?
>
> We do have such a document:
> https://qemu-project.gitlab.io/qemu/system/security.html
> and the AGENTS.md does tell the LLM about it.
>
> It puts all the virtualization accelerators within the
> security use case boundary. Personally I think this is
> reasonable -- the main reasons for having TCG outside it are
> (1) the TCG emulation itself is a lot of code and
> (2) it is a convenient way to rule out an enormous amount
> of old board and device model code in one go.
> This applies much less to the hvf, whpx, etc cases as they are
> using almost exactly the same board/device/core code as KVM.
>
> The idea as I understand it here is that by giving a very
> brief summary of the other document you make sure that the
> important parts we want to emphasize are in the agent's context
> and clearly stated. But I'm no expert on how to craft these
> files...

Yeah compared to normal programming its a bit imprecise - almost like
natural language is full of ambiguity and ad-hoc grammar ;-)

There is essentially a trade off about how many tokens you commit to the
permanent context (system prompt + agents.md + list of skills/rules) so the
agent will load stuff when needed but you don't pay an excessive token
cost for every query. Also while the frontier models have quite large
context windows (200K to 1M tokens) the local open weight models often
have much smaller windows so you need some free for the actual query and
response.

I did "test" this by asking the model how it would route a bunch of
theoretical vulnerabilities and it generally reasoned and "did" the
right thing.

Some of the TUI tools (Claude Code for example) have skill creators that
include evaluations which are then run with and without the additional
context. Another LLM then evaluates the response and scores the response
to give some sort of qualitative indication on if the additional context
is useful. However the workflow for these evaluations is currently tied
to specific providers and I don't think we want to favour one over
another.

However going through this process was one reason I didn't include a git
skill because it doesn't add much, the base models generally already
know how to drive git pretty well. In the end I've just added (to my
local config):

  When applying patches you should assume the user is happy building on top of the current branch. 
  You MUST always ask the user (using the eca__ask_user tool) before changing branches or resetting the git tree state.

to encode my local workflow in the agent and not bothered with any more
details on how to drive git. The same is true for the code explorer
which drops all the gtags and git-grep stuff as having the semcode MCP
provides a much richer set of tools for exploring the code. Instead it
now just focuses on the QEMU specific idiosyncrasies of how our code is
organised.


>
> thanks
> -- PMM

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro