On Sun, 27 Sept 2026 at 16:06, Sasha Levin <[email protected]> wrote: > > On Sun, Sep 27, 2026 at 04:42:06AM +0200, Antheas Kapenekakis wrote: > >I do not have a problem with coding-assistants.rst staying as it is > >now. But it does not make for a good agents.md file. And neither does > >the readme. > > What makes one good? In my tests this one did its job: both agents > followed the kernel's rules, for about 1.3k to 2.4k tokens. If you have > a case where it makes an agent do worse, I'd like to see it.
Small, self contained, direct, lists what an agent needs to do and nothing more. 2.4k tokens is a lot, it equates to around a 5% increase in spend for an agent that compacts at 250k context and has 60% of its billing be cached input tokens. Or a 5% usage reduction. For, in your testing, adding an Assisted-by tag and a no Sign-off tag and closer following of domain subject conventions? The equivalent agents.md file for the behavior described in your initial patch body is: When committing changes in the Linux kernel tree: - follow the conventions of the file (or folder for new files) git history to derive a commit subject and body - Add Assisted-by: LLM (LLM is literal here, only LLM) - Add no Signed-off-by:, only humans can do that By the way, if Co-Authored-By: <model name> <noreply@...> is Claude, the recommended way to fix this is to ask claude to disable attributions by editing your claude config. When Claude goes to commit it gets a system message asking it to add its own attribution. Unfortunately, this is user error unless you like to give Claude free advertising (which I assume with the recent guideline changes you do not) > >I think there might be a misunderstanding with what an agents.md file > >is meant to do. It is meant to be a small file that lists a few > >notable things agents should know about a project. > > The spec at agents.md doesn't say that. It has no required fields or > length, and says anything you'd tell a new teammate belongs there. > OpenAI's own AGENTS.md in the Codex repo is 320 lines, about four times > the size of README. The readme you symlinked is an index of readmes, not a set of instructions and not something you'd tell a new teammate. It is not self contained and when self contained provides no usable information. Ir relies on additional tool calls to derive a policy (more expensive). The codex agents.md is on the larger side, but it still does what I said. It is self contained (other than some API detours that the agent won't take most of the time), and lists how the agent should work with the project. It is also qualifies as "anything you'd tell a new teammate belongs there". > >Why should the kernel make an exception here and say no, this is the > >agents.md file you get > > It's a default for people who haven't written their own, the same as > .clang-format, .cocciconfig, or .pylintrc. Anyone with their own file can > still > use that instead, and the spec says "explicit user chat prompts override > everything". style guides and formatting configs are universal. I doubt any of us have had to change any of those files. No, people cannot replace it with their own. agents.md files are not meant to be replaced. Yes, they can be replaced on their tree. But when switching into a mainline tree for a submission, the default agents.md file comes back so it either has to be universal or gitignored. As you noted, recent codex versions have a .override file, but this is barely documented and not standard. As of two weeks ago, Claude can read agents.md files, but this is not on all occasions and comes with caveats so claude.md is not a replacement. There are also at least four other popular harnesses you did not list alternatives for. People should not rely on undocumented behavior to work with agents on the kernel how they want. You need to address this on your next reply because you skirted this and it is the major issue in your proposal and why it should not get merged. > >what is the point of creating a > >shared agents.md file? Is it to help experienced kernel developers? > > Yes, and everyone else too. README is an index, so it helps the agent > figure out where to find things, whether that's an experienced > developer working in a subsystem or someone asking how some part of the > kernel works. It doesn't help anyone else. README is an index = wastes tool calls and destroys the environment when deployed on a massive scale (as it would if this got picked up), while containing unnecessary information that degrades model performance for everyone You also need to address in your next reply how it helps professional kernel developers (ie is their job), that will find your symlink in every mainline checkout and have to replace it manually if they do not want to degrade their models. They spend 40 hours per week on the kernel and if they want to enhance their agent, they can spend 20 minutes on an agents.md file (which I assume a lot have and this patch will break the workflows of) Addressing the above two comments is not optional and you have not done it yet. I raised them multiple times. > It also covers the patches maintainers get from people who never write > their own. In my tests, two current agents without AGENTS.md got the > basics wrong: one added my Signed-off-by itself, the other added no > attribution. With it, both got it right. > > >Because omitting sign-offs is not helpful, they will need to add one > >even if they do not understand what it is > > If someone adds their sign-off without understanding what it certifies, > that's on them. We can't have agents add it for them just because some > people would ignore its meaning anyway. I didn't say we should make the agent add it. I said if someone wants to do it it is up to them. Not you, not the mainline kernel config, not this patch. And disabling it does nothing because the user does not understand what a sign off is anyway and will add it later or submit without it. In which case you get broken patches anyway and you solved nothing. > If you think a hand-written AGENTS.md would do better, feel free to > write one and propose it. For now, this one seems to be working just > fine. No, I am fine with one not existing and it would be my preference actually. Ideally it would be added to .gitignore as well. That just does not address your need of steering novel contributor plus LLM, which I tried to help with. But if you do not want to put more effort than a symlink then not breaking our workflows is more important so this patch should not merge. Best, Antheas > -- > Thanks, > Sasha >
