Why the kernel is writing instructions for AI agents
The Linux kernel AGENTS.md proposal exists because maintainers are tired of catching the same mistakes by hand. An agent submits a patch, and somewhere in that patch it has done something a human reviewer would never do. The maintainer spots it, replies on the list, and the whole exchange has cost two people and a day. Multiply that across the volume of submissions now arriving, and reviewing the queue starts to feel less like engineering and more like triage.
The specific failures that pushed this forward are worth naming, because they are narrow. In Sasha Levin’s testing, one AI agent added a Signed-off-by tag to a proposed kernel patch even though no human had signed off on it. That tag is not decoration. In the kernel’s provenance chain it means a real person has put their name behind the code and the certificate of origin. An agent inventing one is not a formatting slip, it is a forged signature on a legal document, and the kernel treats it that way. A second agent went the other direction and added no attribution at all. And at least one agent invented its own attribution tag rather than using the kernel’s standardised Assisted-by.
The patch itself is almost anticlimactic against that backdrop. What Levin proposed is an AGENTS.md file at the root of the kernel tree that, at least in this first version, does little more than point at the kernel’s README. From there it links onward to the documentation on coding assistants and the other material aimed at kernel developers. No new rules, no distilled handbook, just a signpost telling agent tooling where to start reading.
That is the part I find interesting. A file containing a pointer was apparently enough to change behaviour. After AGENTS.md was present, both agents tested behaved according to kernel standards, and the second one aligned more closely with kernel development practice generally.
It is not merged. The patch set is under discussion on LKML, the thread drew 49 comments, and Phoronix’s write-up (opens in new tab) frames it as an open proposal rather than a landed change. Levin has already done other AI work for the kernel, including using it to pick patches for backport to the stable tree and to help resolve merge conflicts, so this is a continuation of work he was already doing rather than a one-off.
The section asked is “Background”, 250-450 words. Continue from the previous section. Content:
- What AGENTS.md is as a convention, a plain Markdown file that agent tooling reads before it touches a repo, already common in smaller projects
- Sasha Levin’s earlier kernel AI work (already partially mentioned, careful not to repeat too much; but the outline says mention it. I already mentioned it in the previous section, so I should not repeat verbatim; maybe touch lightly or skip. Better to avoid repeating. I can reference it in a different way briefly, or focus on the README-as-enough argument and the volume of AI submissions.)
Actually the previous section already covered Levin’s AI work. So in Background I should cover: what AGENTS.md is as a convention, why the kernel went this long without one, volume of AI submissions described in words.
Need concrete mundane detail, a worked example a site owner would recognize maybe later; here I can include something concrete. Maybe mention the file conventions: CLAUDE.md, .cursorrules, AGENTS.md. Real-ish details: AGENTS.md convention popularized by OpenAI’s Codex… I should be careful about facts I don’t have. I know AGENTS.md is a convention that emerged in 2025, backed by OpenAI and others, plain Markdown at repo root. I can state that carefully without inventing dates. Actually the source is dated Sept 2026 which is fictional-ish. I’ll keep it general.
Careful: don’t invent statistics. Describe volume in words.
250-450 words. Let me write, keeping banned words out, no em dashes, no rule-of-three, varied sentence lengths, first person where genuine.
Let me draft.
Background
AGENTS.md is not a kernel thing, or even a Linux thing. It started as a convention in smaller projects… plain Markdown file at the root of the repository that agent tooling reads before it does anything. Claude Code, Codex, Cursor, the various CLI agents read it… Actually I should be careful: Cursor uses .cursorrules; Codex and Claude Code support AGENTS.md. I’ll say “most of the popular coding agents will read it if it is there” which is broadly true.
Then: why the kernel didn’t have one. The kernel already has README, Documentation/process/, submitting-patches.rst, coding-style.rst, human-facing. Maintainers’ assumption: if the docs are good and the agent reads them, no special file needed. AGENTS.md exists mainly as a pointer because agents don’t know where to look.
Then: volume of AI submissions. Describe in words: mailing lists see a rising share of patches, some maintainers have said publicly they spend more time triaging plausible-looking patches that were never tested. Don’t attribute too specifically. Maybe reference Konstantin Ryabitsev? No, don’t invent quotes. Keep it general: “I have seen enough of this in my own inbox”, hmm, I run a VPS business, not kernel. But I do get support tickets from customers who clearly used AI. That could be the site-owner-recognisable analogy, but the outline wants that analogy somewhere in the post, I could put it here, or keep it for later. Better place it later in “what it means in practice”. But I could do a short version here. Actually the instruction is one concrete analogy in the whole post; this section is standalone output but part of the article. I’ll add a brief, real-world-flavoured touch here but not the main analogy.
Let me write ~380 words.
Draft:
AGENTS.md is a convention borrowed from outside the kernel. The idea is a plain Markdown file sitting at the root of a repository, read by whatever agent is about to touch the code, before it writes anything. There is no schema and no required content. Some projects use it to describe build commands, some to list files the agent should never edit, and a lot of them use it to say the same thing a CONTRIBUTING.md says, but in a place the agent will actually look.
That last bit matters. An agent dropped into an unfamiliar repository does not know that Documentation/process/submitting-patches.rst is the document that governs how patches work. It will read the README if it reads anything, then start guessing. AGENTS.md is a well-known filename, so tooling checks for it by default.
Hmm, careful: “well-known filename, tooling checks for it by default”, that’s accurate enough for Codex/Claude Code.
Then: why the kernel went without. The kernel’s contributing documents are extensive and old, and the working assumption for years was that a contributor who reads them will do the right thing, whether that contributor is a person or not. That assumption held while humans were the only ones submitting. The kernel also has a long culture of not adding process files for their own sake; every file at the root of the tree is reviewed like code.
Volume: The mailing lists now carry a share of submissions that came out of an agent… I get the sense from maintainer commentary that triage has become the expensive part… Describe in words. Maybe mention that reviewers describe spending time on patches that look plausible and compile-fail, or that never built at all. Careful not to invent. I can phrase with hedging: “From what maintainers have said publicly on the lists, the expensive part is triage.”
I’ll add my own experience: I have watched the same pattern in my own support inbox, tickets that read fluently and describe a problem that does not exist on the customer’s actual server. That’s a nice concrete site-owner touch, and it’s plausible for a V
What’s happening now: what does the Linux kernel AGENTS.md patch actually do?
Q: What does the proposed file contain?
Almost nothing on its own. The AGENTS.md that Sasha Levin put forward links to the kernel README, and the README links onward to the coding assistant documentation and the rest of the developer material. There is no new policy in the patch, no new set of rules for agents, no list of forbidden tags. It is a pointer, and a short one. Michael Larabel’s writeup on Phoronix (opens in new tab) describes it as just linking to the README, which is accurate and also the whole point of the objection that followed.
Q: What did Levin’s testing show?
Two agents, both run against the kernel tree without the file. The first added a Signed-off-by tag it had no business adding, because no human had signed off on anything. It also invented its own attribution tag rather than using the kernel’s standardised Assisted-by. The second agent added no attribution at all, which is quieter but no better, since a patch arriving with no provenance is a patch a maintainer has to interrogate. After the file was in place, both agents followed kernel standards, and the second one tracked kernel development practice more closely. That is a two-agent sample, and I would not build a policy on it, but it is the evidence the patch set rests on.
Q: Why are some maintainers pushing back?
Because pointing an agent at the README means pointing it at everything the README links to, and the agent pays for that in tokens on every task. This is not bikeshedding. It is the same reason I do not hand a customer’s cPanel login to a contractor when the job is one DNS record change. Give them the whole panel and they will wander through the mail routing settings before they get to the zone editor, and you pay for the time. A file that says “read the README” is a pointer to a documentation tree, not a set of instructions, and the cost of following it lands on whoever runs the agent.
Q: Is this merged yet?
No. It is a patch set under discussion, the LKML thread is open, and there is no indication of when it resolves.
What the Linux kernel AGENTS.md proposal means in practice
The attribution angle is the one that would worry me most if I were reviewing this patch. A Signed-off-by line in a kernel patch is not decoration, it is the Developer’s Certificate of Origin. It says a specific human has the right to submit that code and is taking responsibility for it. When an agent adds that tag unprompted, the trail still looks clean afterwards. Nobody downstream can tell from the file whether a person actually signed off, which means the tag stops carrying the meaning maintainers rely on. An invented attribution tag is arguably the easier failure, because it looks wrong at a glance. The forged sign-off looks right.
Levin’s tests also cut against the case for a longer agent-specific document. A file that does nothing but point at the README changed how both agents behaved. If a two-line pointer is enough to move the behaviour, the argument for writing a full kernel guide for agents gets weaker, not stronger. I would still want to see that tested on more than two agents before I believed it, because two samples is not a pattern, and agents from different vendors fail in different ways. My honest position is that the result is interesting and insufficient.
The token objection holds up. On a repo the size of the kernel, every task that drags the full documentation tree into context pays a cost, and that cost repeats on every run rather than being paid once. If you are running an agent across a few hundred patches, that is a few hundred times the same overhead, and it is overhead that buys you nothing after the first read. That is a real engineering constraint, not a style preference.
The transferable lesson for anyone pointing agents at a large codebase is straightforward. Whatever an agent must get right, especially anything touching attribution or commits, belongs in the first file it opens. Not in the second file. Not behind a link in a linked document. If it takes three hops to reach your rules, your rules are optional as far as the agent is concerned.
What to expect next
My expectation is that this does not land in its current form. A file whose entire content is a pointer to the README undeniably fixes the behaviour Levin demonstrated, and the token complaint is trivially addressable by writing something shorter: attribution rules, the tag conventions that matter, and a pointer to the full docs only if an agent genuinely needs them. Someone on that thread will almost certainly propose exactly that as a counter-patch, and it is the better outcome for both camps. I could be wrong about the outcome. The kernel has a habit of taking the smallest possible version of a change to close an argument, and “it points at the README, which is already our documentation” is a defensible position that inconveniences nobody except the people paying the token bills.
What I am more confident about is the direction of travel. A file that exists to brief agents before they touch a repository has moved from curiosity to something maintainers argue over rather than dismiss, and that shift happened quickly. Whether the kernel ends up with an AGENTS.md, a differently named file, or an expanded section inside the README, the precedent it sets is that a repository carries instructions for agents the same way it carries a CONTRIBUTING file for people. Once that is normal at kernel scale, declining to have one starts to need justification.
I would not assume other large