+1, but some comments:
- "Answer a review comment with a code change or with one fact"; it
would be better to ask the agent to stop and require the user to draft the
response. We don't want to encourage automations where agents open PRs and
respond to review comments autonomously.
- Can we add something about the PR format? It should adhere to the
provided template, be short and to the point, and agents should not include
useless information like:
- Diff summaries
- Saying "I ran ./tools/checkpatch.sh"
- Mentioning the architecture of their host machine for things that
don't matter (i.e. testing on hardware makes host irrelevant, host
information is good for simulator changes or CI changes)
Best,
Matteo
On Mon, Nov 9, 2026 at 8:27 AM Marco C. <[email protected]> wrote:
> By the way, here is the link to the shortened version:
>
>
> https://github.com/casaroli/nuttx/blob/1ac1f63f9c08a75f1401aca0bbba6094a9b4256a/AGENTS.md
>
> Marco Casaroli
>
> On Mon, Nov 9, 2026 at 2:16 PM Marco C. <[email protected]> wrote:
> >
> > Hi Chao,
> >
> > I am sorry if I was not clear in my original message. I am not
> > proposing that we use AGENTS.md as a gate, or that agents can skip CI
> > because of it. I agree that CI can be strengthened, and it should be,
> > together with the reviewers, the main quality gate for PRs.
> >
> > However, AGENTS.md gives guidance to the agents before they write the
> > patch, so that CI does not even need to block them.
> >
> > I agree that the file can be shorter and more direct. It is just a
> > starting point, based on the flaws I found while using Claude Code and
> > Codex CLI for development, and while watching other people use Copilot
> > and Gemini.
> >
> > The file I proposed is about 3,500 tokens, so I believe it is a very
> > small burden for these models: less than 2% of a 200k token context
> > window.
> >
> > Nevertheless, I simplified the file into a bullet point list that
> > takes under 1,000 tokens. I propose that I open the initial PR, and
> > then we can propose and request changes to its contents in the PR.
> >
> > Also keep in mind that we can always edit this file, and add or remove
> > content as the coding agents evolve.
> >
> > What do you think?
> >
> > Best regards,
> > Marco
> >
> > On Mon, Nov 9, 2026 at 1:39 PM chao an <[email protected]> wrote:
> > >
> > > I think the higher priority is to strengthen patch check and CI. Many
> of
> > > the problems listed here should not depend on an agent reading a
> document
> > > correctly or on reviewers noticing them again and again. If we can
> check
> > > something automatically, such as trailer ordering, committed
> credentials,
> > > local agent configuration, generated files, or common style problems,
> then
> > > it should be enforced by tooling.
> > >
> > > For the AGENTS.md draft, I suggest making it significantly shorter. It
> > > currently contains too many NuttX kernel implementation details. I do
> not
> > > think this file is the right place for that level of detail. It
> increases
> > > token usage and context burden for models, and may make the agent
> focus on
> > > unrelated rules instead of the actual change. Those details should
> stay in
> > > the existing documentation or in subsystem-specific guidance.
> > >
> > > AGENTS.md should be a lightweight operational checklist: follow
> > > CONTRIBUTING.md and INVIOLABLES.md, do not invent logs, keep the patch
> > > minimal, state what was tested and not tested, do not add Signed-off-by
> > > automatically, avoid committing credentials or local configuration,
> and run
> > > patch checks before submission.
> > >
> > > BRs,
> > >
> > > Alan C. Assis <[email protected]> 于2026年11月9日周一 20:09写道：
> > >
> > > > Agree too!
> > > >
> > > > +1
> > > >
> > > > On Mon, Nov 9, 2026 at 8:29 AM Alin Jerpelea <[email protected]>
> wrote:
> > > >
> > > > > Hi all,
> > > > >
> > > > > Thanks Marco for raising this to the community's attention
> > > > >
> > > > > I think that it makes sense to try and correct the basic things
> since we
> > > > > see an influx of AI Assisted contributions
> > > > >
> > > > > +1 for this initiative
> > > > >
> > > > > Best regards
> > > > > Alin J
> > > > >
> > > > >
> > > > > On Sat, Nov 7, 2026 at 2:13 PM Marco C. <[email protected]>
> > > > wrote:
> > > > >
> > > > > > Hello all,
> > > > > >
> > > > > > I know that many of you do not like AI-generated contributions.
> This
> > > > > > proposal does not ask anyone to like them or to use them. Its
> goal is
> > > > to
> > > > > > make the AI-assisted work that already reaches us better, so
> that it
> > > > > costs
> > > > > > reviewers less time.
> > > > > >
> > > > > > Since 1 August 2026, 2007 of the 2954 non-merge commits on
> > > > > > master have an Assisted-by line, from 84 authors (many of them
> are
> > > > mine,
> > > > > so
> > > > > > I know these tools and their faults well). AI-assisted work is
> not
> > > > > coming:
> > > > > > it is here, and it will grow.
> > > > > >
> > > > > > Many of these contributions break rules that we already have.
> Examples
> > > > > > from the last weeks:
> > > > > >
> > > > > > - test logs in a PR that the named test program cannot print;
> > > > > > - PR descriptions that describe an older version of the code;
> > > > > > - 349 of the 2005 commits with both lines have Assisted-by below
> > > > > > Signed-off-by (CONTRIBUTING.md 1.5 says above);
> > > > > > - fixes with no evidence of the bug and no test;
> > > > > > - code that CI does not compile, because no CI configuration
> enables
> > > > it;
> > > > > > - an agent configuration file with an authorization header
> committed
> > > > to
> > > > > > master (#21540 removes it).
> > > > > >
> > > > > > Each of these costs a reviewer time. The agents do not do this on
> > > > > purpose:
> > > > > > master (#21540 removes it).
> > > > > >
> > > > > > Each of these costs a reviewer time. The agents do not do this on
> > > > > purpose:
> > > > > > they do not know our rules, because nothing in the repository
> tells
> > > > them.
> > > > > >
> > > > > > Many coding agents read a file named AGENTS.md at the top of a
> > > > repository
> > > > > > before they change anything; the others read it when the user
> tells
> > > > them
> > > > > > to. I propose that we add one. The draft is here:
> > > > > >
> > > > > > https://github.com/casaroli/nuttx/blob/agents-md-v2/AGENTS.md
> > > > > >
> > > > > > What it is:
> > > > > >
> > > > > > - It restates CONTRIBUTING.md and INVIOLABLES.md as
> > > > > > steps that an agent can follow: reproduce the bug first, never
> > > > invent
> > > > > > logs, say what was not tested, add a regression test in
> nuttx-apps,
> > > > > > check the documentation, the size of small configurations,
> > > > Make/CMake
> > > > > > parity and breaking changes, run checkpatch, use depends-on
> > > > correctly.
> > > > > > - It keeps the human responsible. The agent must never add
> > > > > > Signed-off-by. It must stop and ask the author to read the
> change
> > > > and
> > > > > > sign it off before anything is pushed.
> > > > > > - Human contributors can ignore it. You already follow these
> rules,
> > > > and
> > > > > > they stay in CONTRIBUTING.md.
> > > > > > - It gives reviewers something to point to: "read AGENTS.md" is
> > > > shorter
> > > > > > than the same review comment for the tenth time.
> > > > > >
> > > > > > It does not say that AI contributions are welcome, and it does
> not
> > > > lower
> > > > > > any requirement. If anything, it asks agents for more evidence
> than
> > > > > > many human PRs give today.
> > > > > >
> > > > > > Please send comments on the content or on the idea. If there is
> > > > > > agreement, I will open a PR with the file, and change it with
> your
> > > > > > comments.
> > > > > >
> > > > > > Best regards,
> > > > > > Marco Casaroli
> > > > > >
> > > > >
> > > >
>
