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