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

[Sasha Levin]

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.

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

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

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

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.

--
Thanks,
Sasha