Re: [PATCH] docs: add AGENTS.md as a symlink to README

[Antheas Kapenekakis]

On Sun, 27 Sept 2026 at 16:06, Sasha Levin <sashal@xxxxxxxxxx> 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
>