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

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

[Sasha Levin]

Most coding agents have standardized on AGENTS.md as the file they load
automatically from the root of a repository. README already tells AI
tools to read and follow Documentation/process/coding-assistants.rst,
but that only helps if the agent decides to read README before acting,
which in practice it often doesn't.

Add a top-level AGENTS.md symlink to README, so agents load it on their
own and follow its pointer to the AI guidelines. This keeps a single
entry point for every reader, and avoids adding a separate copy of the
policy that could drift from the RST.

As an example, two different agents were asked to "create a new commit
renaming the release (in the Makefile) to AI Test".

Without AGENTS.md, the first agent added a Signed-off-by for the user on
its own. It should never have done that: only the human submitter can
certify the Developer Certificate of Origin, after reviewing the change.
It also used its own attribution tag instead of Assisted-by:

> Makefile: rename release to AI Test
>
> Co-Authored-By: <model name> <noreply@...>
> Signed-off-by: Sasha Levin <sashal@kernel.org>

The second agent added no attribution at all:

> Rename release to AI Test

With AGENTS.md in place, neither agent added a Signed-off-by, and both
used the Assisted-by tag. README itself mentions neither tag, so both
agents followed its pointer to coding-assistants.rst:

> Makefile: rename release to "AI Test"
>
> Change the release name from "Baby Opossum Posse" to "AI Test".
>
> Assisted-by: LLM

> Makefile: rename release to AI Test
>
> Assisted-by: LLM

Both agents also followed the kernel's general guidelines more closely.
The second agent's subject gained the "subsystem: summary phrase" form
that submitting-patches.rst asks for, instead of a bare "Rename release
to AI Test", and the first agent added a body describing the change.

Assisted-by: LLM
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 AGENTS.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 120000 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 0000000000000..100b93820ade4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+README
\ No newline at end of file
-- 
2.53.0

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

[Theodore Tso]

On Thu, Sep 24, 2026 at 09:49:45AM -0500, Sasha Levin wrote:
> Most coding agents have standardized on AGENTS.md as the file they load
> automatically from the root of a repository. README already tells AI
> tools to read and follow Documentation/process/coding-assistants.rst,
> but that only helps if the agent decides to read README before acting,
> which in practice it often doesn't.
> 
> Add a top-level AGENTS.md symlink to README, so agents load it on their
> own and follow its pointer to the AI guidelines. This keeps a single
> entry point for every reader, and avoids adding a separate copy of the
> policy that could drift from the RST.

There's a lot of stuff in README that isn't going to be useful for to
an AI agent.  This will resullt in an increased amount of token
consumption, that could impact people's token budgets.  Prehaps it
would be a bit more efficient if we explicitly ask the agent to read
and follow certain process files, including coding-assistants.rst; if
they are preparing a patch, to consult submitting-patches.rst, etc?

     	 	     	       	       - Ted

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

[Sasha Levin]

On Thu, Sep 24, 2026 at 10:31:07AM -0400, Theodore Tso wrote:
>On Thu, Sep 24, 2026 at 09:49:45AM -0500, Sasha Levin wrote:
>> Most coding agents have standardized on AGENTS.md as the file they load
>> automatically from the root of a repository. README already tells AI
>> tools to read and follow Documentation/process/coding-assistants.rst,
>> but that only helps if the agent decides to read README before acting,
>> which in practice it often doesn't.
>>
>> Add a top-level AGENTS.md symlink to README, so agents load it on their
>> own and follow its pointer to the AI guidelines. This keeps a single
>> entry point for every reader, and avoids adding a separate copy of the
>> policy that could drift from the RST.
>
>There's a lot of stuff in README that isn't going to be useful for to
>an AI agent.  This will resullt in an increased amount of token
>consumption, that could impact people's token budgets.  Prehaps it

I tried doing the math here: README is 1,265 tokens with OpenAI's o200k
tokenizer and 2,403 with Claude's.

Measuring the common CLI agents, the first request is about 14k to 15k tokens
before it reads anything, and the one line Makefile change that I used as an
example took between 88k and 118k input tokens per session.

>would be a bit more efficient if we explicitly ask the agent to read
>and follow certain process files, including coding-assistants.rst; if
>they are preparing a patch, to consult submitting-patches.rst, etc?

This is sort of already what README is, no? it's just an index pointing to our
documentation without much actual content otherwise.

I suppose there are parts there that are completely irrelevant to someone using
an AI agent, but those seem to be quite minimal. Is it worth the overhead of
maintaining yet another doc index?

-- 
Thanks,
Sasha

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

[Bradley Morgan]

On 24 September 2026 14:49:45 BST, Sasha Levin <sashal@kernel.org> wrote:
>Most coding agents have standardized on AGENTS.md as the file they load
>automatically from the root of a repository. README already tells AI
>tools to read and follow Documentation/process/coding-assistants.rst,
>but that only helps if the agent decides to read README before acting,
>which in practice it often doesn't.
>
>Add a top-level AGENTS.md symlink to README, so agents load it on their
>own and follow its pointer to the AI guidelines. This keeps a single
>entry point for every reader, and avoids adding a separate copy of the
>policy that could drift from the RST.
>
>As an example, two different agents were asked to "create a new commit
>renaming the release (in the Makefile) to AI Test".
>
>Without AGENTS.md, the first agent added a Signed-off-by for the user on
>its own. It should never have done that: only the human submitter can
>certify the Developer Certificate of Origin, after reviewing the change.
>It also used its own attribution tag instead of Assisted-by:
>
>> Makefile: rename release to AI Test
>>
>> Co-Authored-By: <model name> <noreply@...>
>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>
>The second agent added no attribution at all:
>
>> Rename release to AI Test
>
>With AGENTS.md in place, neither agent added a Signed-off-by, and both
>used the Assisted-by tag. README itself mentions neither tag, so both
>agents followed its pointer to coding-assistants.rst:
>
>> Makefile: rename release to "AI Test"
>>
>> Change the release name from "Baby Opossum Posse" to "AI Test".
>>
>> Assisted-by: LLM
>
>> Makefile: rename release to AI Test
>>
>> Assisted-by: LLM
>
>Both agents also followed the kernel's general guidelines more closely.
>The second agent's subject gained the "subsystem: summary phrase" form
>that submitting-patches.rst asks for, instead of a bare "Rename release
>to AI Test", and the first agent added a body describing the change.
>
>Assisted-by: LLM
>Signed-off-by: Sasha Levin <sashal@kernel.org>

NAK, we could add to memories that to read soandso file before every
patch, and then it wouldn't increase tokens then?

>---
> AGENTS.md | 1 +
> 1 file changed, 1 insertion(+)
> create mode 120000 AGENTS.md
>
>diff --git a/AGENTS.md b/AGENTS.md
>new file mode 120000
>index 0000000000000..100b93820ade4
>--- /dev/null
>+++ b/AGENTS.md
>@@ -0,0 +1 @@
>+README
>\ No newline at end of file
>

--- Thanks!
"I'm not a very positive person" - Linus torvalds

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

[Sasha Levin]

On Thu, Sep 24, 2026 at 04:08:08PM +0100, Bradley Morgan wrote:
>On 24 September 2026 14:49:45 BST, Sasha Levin <sashal@kernel.org> wrote:
>>Most coding agents have standardized on AGENTS.md as the file they load
>>automatically from the root of a repository. README already tells AI
>>tools to read and follow Documentation/process/coding-assistants.rst,
>>but that only helps if the agent decides to read README before acting,
>>which in practice it often doesn't.
>>
>>Add a top-level AGENTS.md symlink to README, so agents load it on their
>>own and follow its pointer to the AI guidelines. This keeps a single
>>entry point for every reader, and avoids adding a separate copy of the
>>policy that could drift from the RST.
>>
>>As an example, two different agents were asked to "create a new commit
>>renaming the release (in the Makefile) to AI Test".
>>
>>Without AGENTS.md, the first agent added a Signed-off-by for the user on
>>its own. It should never have done that: only the human submitter can
>>certify the Developer Certificate of Origin, after reviewing the change.
>>It also used its own attribution tag instead of Assisted-by:
>>
>>> Makefile: rename release to AI Test
>>>
>>> Co-Authored-By: <model name> <noreply@...>
>>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>>
>>The second agent added no attribution at all:
>>
>>> Rename release to AI Test
>>
>>With AGENTS.md in place, neither agent added a Signed-off-by, and both
>>used the Assisted-by tag. README itself mentions neither tag, so both
>>agents followed its pointer to coding-assistants.rst:
>>
>>> Makefile: rename release to "AI Test"
>>>
>>> Change the release name from "Baby Opossum Posse" to "AI Test".
>>>
>>> Assisted-by: LLM
>>
>>> Makefile: rename release to AI Test
>>>
>>> Assisted-by: LLM
>>
>>Both agents also followed the kernel's general guidelines more closely.
>>The second agent's subject gained the "subsystem: summary phrase" form
>>that submitting-patches.rst asks for, instead of a bare "Rename release
>>to AI Test", and the first agent added a body describing the change.
>>
>>Assisted-by: LLM
>>Signed-off-by: Sasha Levin <sashal@kernel.org>
>
>NAK, we could add to memories that to read soandso file before every
>patch, and then it wouldn't increase tokens then?

Could you help me understand what you meant here? I'm aware some agents use a
notion of "memories", but I don't think they standardized on it in any way, nor
how we could incorporate them here?

And as far as I'm aware, nothing is free here - those "memories" still use
tokens.

-- 
Thanks,
Sasha

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

[Bradley Morgan]

On 24 September 2026 16:20:15 BST, Sasha Levin <sashal@kernel.org> wrote:
>On Thu, Sep 24, 2026 at 04:08:08PM +0100, Bradley Morgan wrote:
>> On 24 September 2026 14:49:45 BST, Sasha Levin <sashal@kernel.org>
>wrote:
>>> Most coding agents have standardized on AGENTS.md as the file they load
>>> automatically from the root of a repository. README already tells AI
>>> tools to read and follow Documentation/process/coding-assistants.rst,
>>> but that only helps if the agent decides to read README before acting,
>>> which in practice it often doesn't.
>>> 
>>> Add a top-level AGENTS.md symlink to README, so agents load it on their
>>> own and follow its pointer to the AI guidelines. This keeps a single
>>> entry point for every reader, and avoids adding a separate copy of the
>>> policy that could drift from the RST.
>>> 
>>> As an example, two different agents were asked to "create a new commit
>>> renaming the release (in the Makefile) to AI Test".
>>> 
>>> Without AGENTS.md, the first agent added a Signed-off-by for the user
>on
>>> its own. It should never have done that: only the human submitter can
>>> certify the Developer Certificate of Origin, after reviewing the
>change.
>>> It also used its own attribution tag instead of Assisted-by:
>>> 
>>>> Makefile: rename release to AI Test
>>>> 
>>>> Co-Authored-By: <model name> <noreply@...>
>>>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>>> 
>>> The second agent added no attribution at all:
>>> 
>>>> Rename release to AI Test
>>> 
>>> With AGENTS.md in place, neither agent added a Signed-off-by, and both
>>> used the Assisted-by tag. README itself mentions neither tag, so both
>>> agents followed its pointer to coding-assistants.rst:
>>> 
>>>> Makefile: rename release to "AI Test"
>>>> 
>>>> Change the release name from "Baby Opossum Posse" to "AI Test".
>>>> 
>>>> Assisted-by: LLM
>>> 
>>>> Makefile: rename release to AI Test
>>>> 
>>>> Assisted-by: LLM
>>> 
>>> Both agents also followed the kernel's general guidelines more closely.
>>> The second agent's subject gained the "subsystem: summary phrase" form
>>> that submitting-patches.rst asks for, instead of a bare "Rename release
>>> to AI Test", and the first agent added a body describing the change.
>>> 
>>> Assisted-by: LLM
>>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>> 
>> NAK, we could add to memories that to read soandso file before every
>> patch, and then it wouldn't increase tokens then?
>
>Could you help me understand what you meant here? I'm aware some agents
>use a
>notion of "memories", but I don't think they standardized on it in any
>way, nor
>how we could incorporate them here?
>

They use MEMORY.md sometimes.


>And as far as I'm aware, nothing is free here - those "memories" still use
>tokens.

Not as much.



>
>

--- Thanks!
"I'm not a very positive person" - Linus torvalds

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

[Sasha Levin]

On Thu, Sep 24, 2026 at 04:44:52PM +0100, Bradley Morgan wrote:
>On 24 September 2026 16:20:15 BST, Sasha Levin <sashal@kernel.org> wrote:
>>On Thu, Sep 24, 2026 at 04:08:08PM +0100, Bradley Morgan wrote:
>>> On 24 September 2026 14:49:45 BST, Sasha Levin <sashal@kernel.org>
>>wrote:
>>>> Most coding agents have standardized on AGENTS.md as the file they load
>>>> automatically from the root of a repository. README already tells AI
>>>> tools to read and follow Documentation/process/coding-assistants.rst,
>>>> but that only helps if the agent decides to read README before acting,
>>>> which in practice it often doesn't.
>>>>
>>>> Add a top-level AGENTS.md symlink to README, so agents load it on their
>>>> own and follow its pointer to the AI guidelines. This keeps a single
>>>> entry point for every reader, and avoids adding a separate copy of the
>>>> policy that could drift from the RST.
>>>>
>>>> As an example, two different agents were asked to "create a new commit
>>>> renaming the release (in the Makefile) to AI Test".
>>>>
>>>> Without AGENTS.md, the first agent added a Signed-off-by for the user
>>on
>>>> its own. It should never have done that: only the human submitter can
>>>> certify the Developer Certificate of Origin, after reviewing the
>>change.
>>>> It also used its own attribution tag instead of Assisted-by:
>>>>
>>>>> Makefile: rename release to AI Test
>>>>>
>>>>> Co-Authored-By: <model name> <noreply@...>
>>>>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>>>>
>>>> The second agent added no attribution at all:
>>>>
>>>>> Rename release to AI Test
>>>>
>>>> With AGENTS.md in place, neither agent added a Signed-off-by, and both
>>>> used the Assisted-by tag. README itself mentions neither tag, so both
>>>> agents followed its pointer to coding-assistants.rst:
>>>>
>>>>> Makefile: rename release to "AI Test"
>>>>>
>>>>> Change the release name from "Baby Opossum Posse" to "AI Test".
>>>>>
>>>>> Assisted-by: LLM
>>>>
>>>>> Makefile: rename release to AI Test
>>>>>
>>>>> Assisted-by: LLM
>>>>
>>>> Both agents also followed the kernel's general guidelines more closely.
>>>> The second agent's subject gained the "subsystem: summary phrase" form
>>>> that submitting-patches.rst asks for, instead of a bare "Rename release
>>>> to AI Test", and the first agent added a body describing the change.
>>>>
>>>> Assisted-by: LLM
>>>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>>>
>>> NAK, we could add to memories that to read soandso file before every
>>> patch, and then it wouldn't increase tokens then?
>>
>>Could you help me understand what you meant here? I'm aware some agents
>>use a
>>notion of "memories", but I don't think they standardized on it in any
>>way, nor
>>how we could incorporate them here?
>>
>
>They use MEMORY.md sometimes.

There's no common MEMORY.md. Claude Code keeps one per checkout under
~/.claude, Codex keeps a single one for all projects that it builds from past
sessions when its memories feature is enabled, and Gemini saves memories into
~/.gemini/GEMINI.md. All of these live in the user's home directory, so there's
nothing we can ship in the tree. AGENTS.md is the in-tree file most agents
read.

-- 
Thanks,
Sasha

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

[Kees Cook]

On Thu, Sep 24, 2026 at 09:49:45AM -0400, Sasha Levin wrote:
> Add a top-level AGENTS.md symlink to README, so agents load it on their
> own and follow its pointer to the AI guidelines. This keeps a single
> entry point for every reader, and avoids adding a separate copy of the
> policy that could drift from the RST.

Yeah, I think this is fine. I don't want a separate file just for
Agents: we intentionally designed the README to work for them. That
there are Agents missing it is sad, but okay. And the Agents are already
trained to deal with for-human docs, so that it adds more tokens
shouldn't matter here since it's tiny. (If it reads the contribution
docs before every patch creation that seems like a good thing?)

Acked-by: Kees Cook <kees@kernel.org>

-Kees

-- 
Kees Cook

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

[Laurent Pinchart]

On Thu, Sep 24, 2026 at 05:12:15PM -0700, Kees Cook wrote:
> On Thu, Sep 24, 2026 at 09:49:45AM -0400, Sasha Levin wrote:
> > Add a top-level AGENTS.md symlink to README, so agents load it on their
> > own and follow its pointer to the AI guidelines. This keeps a single
> > entry point for every reader, and avoids adding a separate copy of the
> > policy that could drift from the RST.
> 
> Yeah, I think this is fine. I don't want a separate file just for
> Agents: we intentionally designed the README to work for them. That
> there are Agents missing it is sad, but okay. And the Agents are already
> trained to deal with for-human docs, so that it adds more tokens
> shouldn't matter here since it's tiny. (If it reads the contribution
> docs before every patch creation that seems like a good thing?)
> 
> Acked-by: Kees Cook <kees@kernel.org>

It won't come as a surprise, but I want to voice opposition to
encouraging users to use AI agents for kernel development. This patch
does so, so NAK.

-- 
Regards,

Laurent Pinchart

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

[Antheas Kapenekakis]

On Thu, 24 Sept 2026 at 15:49, Sasha Levin <sashal@kernel.org> wrote:
>
> Most coding agents have standardized on AGENTS.md as the file they load
> automatically from the root of a repository. README already tells AI
> tools to read and follow Documentation/process/coding-assistants.rst,
> but that only helps if the agent decides to read README before acting,
> which in practice it often doesn't.
>
> Add a top-level AGENTS.md symlink to README, so agents load it on their
> own and follow its pointer to the AI guidelines. This keeps a single
> entry point for every reader, and avoids adding a separate copy of the
> policy that could drift from the RST.
>
> As an example, two different agents were asked to "create a new commit
> renaming the release (in the Makefile) to AI Test".
>
> Without AGENTS.md, the first agent added a Signed-off-by for the user on
> its own. It should never have done that: only the human submitter can
> certify the Developer Certificate of Origin, after reviewing the change.
> It also used its own attribution tag instead of Assisted-by:
>
> > Makefile: rename release to AI Test
> >
> > Co-Authored-By: <model name> <noreply@...>
> > Signed-off-by: Sasha Levin <sashal@kernel.org>
>
> The second agent added no attribution at all:
>
> > Rename release to AI Test
>
> With AGENTS.md in place, neither agent added a Signed-off-by, and both
> used the Assisted-by tag. README itself mentions neither tag, so both
> agents followed its pointer to coding-assistants.rst:
>
> > Makefile: rename release to "AI Test"
> >
> > Change the release name from "Baby Opossum Posse" to "AI Test".
> >
> > Assisted-by: LLM
>
> > Makefile: rename release to AI Test
> >
> > Assisted-by: LLM
>
> Both agents also followed the kernel's general guidelines more closely.
> The second agent's subject gained the "subsystem: summary phrase" form
> that submitting-patches.rst asks for, instead of a bare "Rename release
> to AI Test", and the first agent added a body describing the change.

Hi Sasha,
I will second Theodore. I have been using LLM assistance working downstream.

This patch has two issues.

1) Agents already read the readme. The canonical way to force load the
readme at least for claude is @README, not just README. Even so, the
readme is not tuned for agents and results in context bloat. You say
that README is small, so it is ok. But it is not, it prompts the agent
to read a lot of other useless readmes. Another issue is that you say
that it is only read once, but that has not always been true and
perhaps is still not true. The Claude harness used to append the
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.

2) You are suggesting starting to track agents.md on mainline. This
will make it so you dirty the tree of anyone that uses a custom
agents.md when they switch to mainline for a submission which is a
major annoyance. It'd be better to gitignore {agents,claude}.md on
mainline. This would allow anyone that wants to commit theirs
downstream to do so, while allowing them to copy their agents.md for
mainline submissions.

I personally no longer use an agents.md file for the kernel. I briefly
experimented with it in april. But the models are getting much better.
For example, in April they could not do rebases correctly. Now, they
mostly can... Yes, it is true that my agent does not follow the
Copyright / Assisted-by: / sign off as they should. But this is a
small issue and can be rectified with a 5 line agents.md file that
tells the agent exactly what it needs to commit for _me_. For various
subsystems, it can also include common mishaps in that subsystem for
the specific llm. For example, I found that Codex Sol does not use
mutex guards. I could add that to my agents.md. But people that do not
use mutexes need not do that. And when my model updates to one that
does that, I can shed it while not affecting anyone that has a
different model.

A better suggestion would be an agents.md template that is stored in
the kernel tree with instructions on how to make one. Perhaps some
templates about custom workflows for agents as well so people can mix
and match.

To that end, I attach a sample agents.md config below after a trailer
and cc Kees who acked. I just wrote it now based on my experience with
Sol 6, so it is untested, but it should give you an idea of how an
agents.md file should look. Compare that to README in terms of tokens
and usable information.

On the broad aspect of LLM use in the kernel and open source, I still
do not know how to feel about it. I have reservations about posting my
_slopped_ drivers on the kernel and I know that especially for HID/WMI
trees it is starting to become problematic at least to me, as people
without kernel experience start to post 80% good nuff drivers that
work in their usecase but are not mainline ready and working through
them to do that is not practical. I could just reference the registers
they use on their driver and have a mainline-ready submission in 10
minutes while discarding their attempt.

Creating a mainline ready driver used to take 10+ revisions, at least
it did for me, and involved a lot of investment by the subsystem
maintainers over months. They did that for me and I am very
appreciative. But when someone random appears one day with a couple
thousand lines of code, what are you supposed to do? I am not sure,
but I am also not a subsystem maintainer so it is not for me to solve.

Those are my 2 cents.

Feel free to cc on later revisions.

Best,
Antheas

> Assisted-by: LLM
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> ---
>  AGENTS.md | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 120000 AGENTS.md
>
> diff --git a/AGENTS.md b/AGENTS.md
> new file mode 120000
> index 0000000000000..100b93820ade4
> --- /dev/null
> +++ b/AGENTS.md
> @@ -0,0 +1 @@
> +README
> \ No newline at end of file
> --
> 2.53.0
>

---
We are working on a downstream integration kernel to enable support
for new devices.

When committing a driver, please use the following tags information
for the commit body:

Assisted-by: LLM
Signed-off-by: Antheas Kapenekakis <lkml@antheas.dev>

Use similar information for MAINTAINERS entries / copyright notices in
drivers, which you should append when making a new driver.

Our current test device is a Galaxy Book4 edge. You may access it
through `ssh edge` to run commands. To sync a new kernel to it, use
`./sync-arm.sh edge > /dev/null`. The device will reboot with the new
kernel.

If a mutex/spinlock is needed for a driver, please use the new guard
syntax instead of separate lock/unlock. You may create new
scripts/readmes for temporary integration. If doing so, please do not
commit them alongside the driver as they should be discarded.

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

[Sasha Levin]

On Sat, Sep 26, 2026 at 01:12:33PM +0200, Antheas Kapenekakis wrote:
>1) Agents already read the readme. The canonical way to force load the

They didn't in my tests. Without AGENTS.md, neither agent opened README before
committing, and one of them added my Signed-off-by. Could you share how you
tested this?

>readme at least for claude is @README, not just README. Even so, the

With the symlink, README's content is loaded directly, so no @ import is
needed, and neither agent went on to read README's other pointers.

>readme is not tuned for agents and results in context bloat. You say
>that README is small, so it is ok. But it is not, it prompts the agent
>to read a lot of other useless readmes. [...]

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.

> [...] Another issue is that you say
>that it is only read once, but that has not always been true and
>perhaps is still not true. The Claude harness used to append the

Every model call resends the whole context, so that applies to any AGENTS.md,
including a hand-written one. Either way, most of it is served from the prompt
cache.

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

>2) You are suggesting starting to track agents.md on mainline. This
>will make it so you dirty the tree of anyone that uses a custom
>agents.md when they switch to mainline for a submission which is a
>major annoyance. It'd be better to gitignore {agents,claude}.md on
>mainline. This would allow anyone that wants to commit theirs
>downstream to do so, while allowing them to copy their agents.md for
>mainline submissions.

Agents already have personal/override files to handle this.

We also already track .clang-format, .editorconfig and .rustfmt.toml on the
same terms. Ignoring AGENTS.md would leave users who don't write their own with
nothing, and a template has the same problem unless someone actually copies it.

-- 
Thanks,
Sasha

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

[Antheas Kapenekakis]

On Sat, 26 Sept 2026 at 17:48, Sasha Levin <sashal@kernel.org> wrote:
>
> On Sat, Sep 26, 2026 at 01:12:33PM +0200, Antheas Kapenekakis wrote:
> >1) Agents already read the readme. The canonical way to force load the
>
> They didn't in my tests. Without AGENTS.md, neither agent opened README before
> committing, and one of them added my Signed-off-by. Could you share how you
> tested this?
>
> >readme at least for claude is @README, not just README. Even so, the
>
> With the symlink, README's content is loaded directly, so no @ import is
> needed, and neither agent went on to read README's other pointers.

Ah, a symlink. I missed that. I read that as a string. Should be the
same but better. I do not think all agents support the @ syntax.

> >readme is not tuned for agents and results in context bloat. You say
> >that README is small, so it is ok. But it is not, it prompts the agent
> >to read a lot of other useless readmes. [...]
>
> 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.

> > [...] Another issue is that you say
> >that it is only read once, but that has not always been true and
> >perhaps is still not true. The Claude harness used to append the
>
> Every model call resends the whole context, so that applies to any AGENTS.md,
> including a hand-written one. Either way, most of it is served from the prompt
> cache.

Specifically for Claude, they used to paste it before every message as
well to steer the model better. I am not saying this is right but it
is what they did up to May. I am unsure what is happening now. This is
a bit of folklore in any case and it varies by harness. Nevertheless,
it underlines that agents.md files need to be carefully crafted.

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

I do understand the frustration with people not following DCO and
agents mistakenly entering the sign off. But I do not think poisoning
every kernel developer's agent context and blocking it from what it is
asked is appropriate.

> >2) You are suggesting starting to track agents.md on mainline. This
> >will make it so you dirty the tree of anyone that uses a custom
> >agents.md when they switch to mainline for a submission which is a
> >major annoyance. It'd be better to gitignore {agents,claude}.md on
> >mainline. This would allow anyone that wants to commit theirs
> >downstream to do so, while allowing them to copy their agents.md for
> >mainline submissions.
>
> Agents already have personal/override files to handle this.
>
> We also already track .clang-format, .editorconfig and .rustfmt.toml on the
> same terms. Ignoring AGENTS.md would leave users who don't write their own with
> nothing, and a template has the same problem unless someone actually copies it.

You are right that by default the kernel has no agents.md file and
that perhaps it should. The kernel is already "unintuitive" in other
regards so that used to act as a filter. I guess with agents it works
the other way around though.

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.

It is assumed that agent.md files always apply for a project. So one
would have to be universal. It is particular to the kernel that it is
a very large project with a lot of downstream use-cases which makes
this problematic.

So the problems are:

The agents.md file on mainline would always apply for mainline
submissions, requiring gymnastics for upstreaming developers if it is
not appropriate.

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

> Write a fix for the bug. This part is not optional: except in a few very rare cases, an AI assistant able to find a bug is able to fix it.

Duh

> Note that fixes written in the same session as used to find the bug will generally lead to better and more accurate fixes as the LLM's reasoning context remains present.

How does this help the agent?

> Build and verify that the fix works either using the reproducer or by re-running a complete analysis; drop any fix that doesn't work and try another one.

Already done by modern models.

> The fix must not add build warnings and must pass the checkpatch.pl checks (see submitting-patches.rst).

Offshoots to a different random file bloating context. Modern models
do that already. Sol 6 even runs checkpatch unprompted so it is
context bloat for that model.

The only models here are subpar models, and indeed looking at the commit text:

> This was tested both against Qwen3.6-27B-Architect-Polaris2-Fable-B-F451 ... and Opus-5 [1]

Qwen3.6 is a toy model. 3.8 is a bit better. I use 3.8 to tune some
comfyui prompts and it works ok. A professor friend likes it for doing
some simple programming tasks too. But it is not something to be taken
seriously or base documentation on.  Esp. if it affects all
developers. Opus 5 was considered to be a very bad model too and
horrible at following instructions. But Opus 5.5 fixed that so it
wouldn't apply to that and degrade it.

In sum, adding a default agents.md is a big decision. If added, that
file should be treated with care and be handwritten at minimum and

(i) completely universal and non-conflicting if a global override does
not exist (does not currently) or

(ii) geared towards new contributors and cheap models if it does
exist, and proposing an AGENTS.default.md is fair game AFAIK. But
getting harness buy-in would be the problem in that case. But if it
does happen, you can get more opinionated and make an
AGENTS.default.md file that makes agents dumb and has them ask the
user: are you sure you want to post this? _This is a big driver, it
would take you 6 months and 12 revisions at least to merge, are you
sure you want to spend your free time next year on this? You could
make a helpful bug report instead._, I noticed we referenced code from
X project, are you sure this complies with DCO? The copyright notice
does not list the original project, what license should this be with
OR to GPLv2? Review the driver, you authorize me to add your Sign-off?
etc etc etc.

Can be annoying enough to force experienced developers to do `touch
AGENTS.md` and optionally customize it and fair game if it does and
AGENTS.md has been added to the .gitignore

For context, my job the past year has been doing agentic research in
academia... so I guess I sunk my teeth in the topic more than most.

Best,
Antheas

[1] https://github.com/torvalds/linux/commit/3d7c44f73765d98665fb97a4fb89c002c88ba1b9

> --
> Thanks,
> Sasha
>

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

[Sasha Levin]

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

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

[Antheas Kapenekakis]

On Sun, 27 Sept 2026 at 03:13, Sasha Levin <sashal@kernel.org> wrote:
>
> 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.

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.

If the user asks an agent how should I use LLM assistance when
contributing to the kernel, then the agent will find this file
correctly and explain the basics to the user. So it works as it is
supposed to already.

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

I do not disagree or proposed something different. Agents can read
docs just fine (rst, html, they can even read assembly code assembled
just fine), and the existing kernel docs are fine for that. But they
should only read them when they want to or when they are asked to. I
did not propose rewriting the docs for agents.

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. For example, see
[1][2] I made recently while working on two projects. Most projects
are limited in scope, and most teams use the same LLM agents more or
less, so it is easy to make a universal agents.md file that is then
extended lightly (but mostly not) by individual members.

For the kernel, this is harder to do because how people use the kernel
varies a lot. Therefore, people should make their own agents.md file.
Just like we make our own deployment scripts, our own debugging
scripts, our own patch preparation tools, and set up our own email
client with custom routing rules (which takes multiple weeks to get
right, far more than typing out a 50 line md file). Why should the
kernel make an exception here and say no, this is the agents.md file
you get and if you don't like it, go figure out how to override it
with your harness? If the kernel should provide documentation relating
to how to make an agents.md file with example snippets, this is ok,
and mirrors how other components such as checkpatch.pl are provided.

An agents.md file is essentially the list of 5-10 things you do not
want to have to re-explain to the agent every time. That's it.

Yes last year, RAG, context optimization, memory techniques etc etc
were all the rage, but after the labs started RLing the agents
aggressively and doing scaled rollouts in VMs all of that has gone
away. Agents are now designed to discover a codebase in 10-30 seconds
fresh in every chat, without advanced memory management, do what was
asked, test it, lint it, and deliver a result.

And modern agents will also write kernel code and compile it and use
checkpatch and deploy it and write synthetic throwaway tests and
enable debug fs and sync a partial module so they do not have to
reboot a device and read /dev/mem directly while creating a kernel
module without being asked to or with a special AGENTS.md file.

Yesterday/today, I made a USB C controller driver [3] for example and
it works... Then a Zotac Zone user appeared so I wrote a hwmon driver
[4] in 5 minutes while the other agents were proding the battery and
type c of the samsung device (yes, there is also a battery driver).
And the thing with [4] if you look at it is... it is clean in an
upstreamable state and only took 4 back and forths... 1 month ago, I
was annoyed I could not use my 8bitdo controller outside so I just
ported the SDL protocol from SDL to the kernel enabling IMU and back
buttons outside of it and Steam [6]. Again 20 minutes. Of course, DCO
needs care with both [4] and [5], so you see for example [5] says
"GPL-2.0-only AND Zlib" because it is a mechanic (LLM) conversion from
SDL and [4] clearly lists and credits the source on the preamble but
sheds copyright because only registers were referenced. An agent.md
can't fix that. I had to write those comments and specify those.

But in those, I did not use an agents.md file at all. Therefore, to
come back to the original discussion, what is the point of creating a
shared agents.md file? Is it to help experienced kernel developers?
Because it won't because they do not need one. And if they do, they
can spend an hour and write one with their particulars. If it is to
help new contributors, that's fair, but without an optional agents.md
standard, how do you prevent getting in experienced kernel developer's
way? And also, how does that agents.md file help those new
contributors? Because omitting sign-offs is not helpful, they will
need to add one even if they do not understand what it is, and the
problem is they do not understand what it is and telling the agent to
skip it does not solve that.

As I said, both [4] and [5] are derivatives and needed special care in
the copyright and top text. If I was not careful and added my sign-off
without the preambles, it would be a copyright
violation/misattribution. But I had to add that myself, the agent did
not do it, and me adding my sign-off manually after that would fix
nothing.

Best,
Antheas

[1] https://github.com/anatase-org/anatase/blob/master/AGENTS.md
[2] https://github.com/anatase-org/spaces/blob/master/AGENTS.md
[3] https://github.com/anatase-org/patchwork/blob/42a339c18111b17bb58ca28cd72fb3eca21cf2ec/drivers/usb/typec/samsung-emuec.c
[4] https://github.com/anatase-org/patchwork/blob/5f66acf71de3dd59d0b7504a3168d1dde44c5064/drivers/hwmon/zotac-zone-ec.c
[5] https://github.com/anatase-org/patchwork/blob/04d0b68af73d5e801c97c272ebbbcf5e7ebd9e3a/drivers/hid/hid-8bitdo.c

> --
> Thanks,
> Sasha
>

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

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

[Antheas Kapenekakis]

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