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