[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

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

[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