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