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
