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

[Sasha Levin <sashal@kernel.org>]

On Sat, Sep 26, 2026 at 07:54:27PM +0200, Antheas Kapenekakis wrote:
>> It didn't in my tests either. With AGENTS.md pointing at README, one agent read
>> only coding-assistants.rst, and the other read that plus generated-content.rst,
>> which coding-assistants.rst references. Neither opened any of README's other
>> pointers.
>
>They usually read it when they need to. I find it is 60% of the time.
>Of course, this does not compensate for behavior that should always
>apply. Sol 6 also has the annoying habit of modifying readmes
>randomly.

Agreed, and the rules in coding-assistants.rst are the part that should
always apply.

>> >agents.md file before every message. Unsure if it still does, I do not
>> >use Claude. agent.md files should be specifically designed for agents
>> >and handwritten. Moreover, they usually need to be tuned for the model
>> >generation in general, if not the provider and model specifically.
>> >Which brings us to 2.
>>
>> The rules README points to (DCO, Assisted-by, patch format) are the same for
>> every model. Personal and model-specific tuning belongs in a personal file.
>> Your sample shows why the shared part should come from the tree: it asks the
>> agent to add your Signed-off-by, which coding-assistants.rst says an agent must
>> never do.
>
>You are correct. Agents are tools. All of their outputs are the
>responsibility of their users. They cannot apply DCO.
>
>For me, I make sure to review copyright and test my kernel patches
>before sending them or pushing them to a remote. So my agent should
>add my sb and the assisted tag otherwise the patches need unnecessary
>cleanup. This is my personal preference. The mainline branch should
>not poison my agent's context or provide conflicting instructions.

Your issue is with coding-assistants.rst, which says agents must not add
Signed-off-by. AGENTS.md only makes agents see it.

[ ... ]

>But as far as I know personal snippets are meant to be additive. I do
>not think there is a widespread override for agents.md for the default
>one. Codex seems to have one but there is only one google result on
>it.

Codex reads AGENTS.override.md in place of AGENTS.md. Claude Code doesn't load
AGENTS.md at all when a CLAUDE.md exists, and Gemini reads GEMINI.md unless
configured otherwise.

The agents are designed exactly for this model: the upstream project has it's
own AGENT.md which is relevant for the upstream side of things. Downstream is
able to modify it as needed, either by carrying an out of tree patch, an
override file, or whatever else works for downstream.

>A large generic readme that offshoots to 30 other readmes is not an
>appropriate agents.md file.
>Documentation/process/coding-assistants.rst would be a better start
>for a symlink but even that is not particularly lean and would likely
>degrade modern agents. It still contains offshoots to 4 different

Changes to coding-assistants.rst itself are fair game as separate patches. This
one only gets agents to load what we already ask them to follow. There's no
substance here - we're just making dumb machines behave better.

>readmes, and the "Procedure for finding and fixing bugs" would degrade
>most modern models. They are already RL'd to do what they are asked,
>and conflicting instructions could lead them to e.g., commit when not
>asked to. For example consider:

[ snip ]

I get that you have concerns with those docs, so feel free to propose patches
for these.

I do not thing we need a seperate machine-only readable set of docs. If these
"agents" can't do better parsing those docs, then we shouldn't bend over and
write them their own versions. I'm okay with doing better at pointing to those
docs ("RTFM!"), but I don't think that a fork of the docs is sensible.

If you disagree, feel free to propose changes to coding-assistants.rst, as this
is really a doc that gets read mostly by machines.

-- 
Thanks,
Sasha