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