Linux Kernel Devs Are Fighting Over an AGENTS.md File. Here's Why
Sasha Levin proposed adding AGENTS.md to the Linux kernel for AI coding agents. Maintainers pushed back. Here's the full debate.
What is AGENTS.md and why is the Linux kernel debating it?
AGENTS.md is a plain text file that sits at the root of a code repository and gives AI coding agents standing instructions: where key documents live, what conventions to follow, what not to do. Most AI coding tools have settled on this filename as something they load automatically when they start working in a repo (Claude is the holdout, preferring CLAUDE.md, though it can be pointed at AGENTS.md or symlinked to it). NVIDIA engineer Sasha Levin proposed adding one to the Linux kernel by symlinking AGENTS.md to the kernel’s existing README. The idea sounds procedural. It turned into a genuine argument on the Linux Kernel Mailing List (LKML) about tokens, maintainability, and whether the kernel should accommodate AI tooling at all.
TL;DR
- Sasha Levin’s patch proposed symlinking a top-level AGENTS.md to the kernel’s README so agents would automatically find pointers to the kernel’s existing AI usage guidelines in
Documentation/process/coding-assistance.rst. - The core objection from Theodore Ts’o and others is that README contains a lot of content irrelevant to AI agents, and loading it on every agent session risks unnecessary token consumption.
- A real test showed the problem AGENTS.md solves: without it, one test agent added a
Signed-off-bytag on its own (something only a human should certify) and another used the wrong attribution tag; with AGENTS.md in place, both agents correctly used the kernel’s “Assisted-by” convention. - Laurent Pinchart rejected the premise entirely, voicing opposition to encouraging AI-assisted kernel development in any form, not just to this specific patch.
- One maintainer argued the kernel isn’t one project but a collection of subsystems with wildly different workflows, so a single generic AGENTS.md makes less sense than per-subsystem or per-developer files, several of which were shared as examples.
- A later thread reframed the symbolism: critics argued that merely having an AGENTS.md file signals “this project accepts LLM code” and could be read as an invitation to submit AI-generated patches without adequate human review.
- No resolution emerged in the thread, and the debate highlights a broader tension in the open source world between codifying AI workflows versus resisting them.
What problem was Sasha Levin trying to solve?
The kernel’s README already tells AI tools to read Documentation/process/coding-assistance.rst, the project’s actual policy on AI use. The problem is that an agent only picks up that instruction if it reads the README first, and in practice it often doesn’t. AGENTS.md exists specifically to be the file agents check automatically, without being told to. Levin’s patch just symlinked AGENTS.md to README so that pointer would reliably get read.
To demonstrate the effect, a basic test was run: an agent was asked to make a small change (effectively renaming a release) with and without the symlink in place. Without AGENTS.md, one agent added a Signed-off-by line on its own, something that should only ever be added by the human submitter, since it certifies the Developer’s Certificate of Origin. A second agent, in the same no-AGENTS.md condition, skipped attribution entirely. With AGENTS.md symlinked to README, both agents instead used the kernel’s “Assisted-by” tag, which is the convention the project’s actual documentation calls for. It’s a small test, but it shows the file doing exactly what it’s meant to do: making agents follow policy without a human having to repeat it every session.
What are the objections to adding AGENTS.md?
The pushback came in layers.
Token bloat. Theodore Ts’o’s objection was first and most direct: README has plenty of content that’s irrelevant to an AI agent, and loading all of it on every single interaction wastes tokens. His proposed fix was narrower: have agents read specific process files (like coding-assistance.rst or submitting-patches.rst) only when relevant, rather than pulling in the whole README every time.
It doesn’t even work reliably. Another developer pointed out that agents don’t uniformly treat these files the same way. Forcing an agent to load README isn’t guaranteed through the generic filename alone; with Claude, for example, you may need to explicitly reference “@README” to force a load. There was also uncertainty about whether some agent harnesses re-append the AGENTS.md content before every message rather than reading it once, which would multiply the token cost problem rather than solve it.
The kernel isn’t one project. A more structural argument came from a developer who said they’d already tried and abandoned a generic AGENTS.md for kernel work. Their point: the kernel is really a collection of loosely related subsystems, each with different conventions, different common mistakes, and often different preferred models. A generic file can’t capture subsystem-specific quirks (like a particular model’s tendency to misuse a locking primitive) without becoming bloated or irrelevant to people working in unrelated areas. Their counter-proposal was a template with instructions for writing your own AGENTS.md, plus example snippets for different workflows, similar to how the kernel already ships tools like checkpatch.pl rather than one-size-fits-all policy.
Built like a system. Not vibe-coded.
Remy manages the project — every layer architected, not stitched together at the last second.
Outright opposition to AI in the kernel. Laurent Pinchart’s objection wasn’t about implementation details at all. He stated plainly that he opposes encouraging AI agents for kernel development and voted to reject the patch on that basis. It’s a position that exists independently of how well-crafted any AGENTS.md file might be.
Symbolic concerns. A later thread raised a different angle: the mere presence of an AGENTS.md file signals to both humans and AI tools that a project “accepts” LLM-generated code. Critics worried this could be read by inexperienced or careless contributors as permission to submit heavily AI-generated patches without the review rigor the kernel normally demands, a dynamic sometimes called “vibe coding” or, more bluntly, “meat proxying” (a human acting as an uncritical relay for AI output).
Is a shared AGENTS.md actually useful for experienced contributors?
Several maintainers argued no, not really. The reasoning: experienced kernel developers already know the submission process, coding style, and tagging conventions cold. They don’t need a file reminding them. If they do want an agent to follow specific conventions, writing a five to ten line personal AGENTS.md takes far less effort than most of the other tooling kernel developers already maintain, like custom email client routing rules for patch review, which can take weeks to configure.
The more interesting question raised was whether a shared file would help newer or occasional contributors instead. One reply was skeptical here too: telling an agent to add a sign-off tag doesn’t help a contributor understand why that tag matters or what it legally represents. The file can make an agent produce kernel-shaped output, but it can’t substitute for a human understanding the submission’s implications. That gap, several participants suggested, is really a review process question, not a file format question.
Did the kernel community reach a resolution?
Not according to the discussion. The thread moved from a narrow technical proposal (symlink AGENTS.md to README) into a broader disagreement about tokens, subsystem variability, the value of standardization versus personalization, and finally into a philosophical dispute over whether the kernel should formally acknowledge AI tooling at all. Some participants offered concrete alternatives, like publishing a documented template rather than a single canonical file. Others rejected the entire premise. No consensus patch had landed as of the discussion covered here.
Frequently Asked Questions
What is AGENTS.md used for?
It’s a file placed at the root of a code repository that gives AI coding agents context and instructions specific to that project, things like coding conventions, required tags, and pointers to documentation, so developers don’t have to repeat the same instructions in every session.
Why doesn’t Claude use AGENTS.md directly?
Claude’s tooling defaults to a file named CLAUDE.md instead. Many projects work around this by symlinking CLAUDE.md to AGENTS.md (or vice versa) so both naming conventions point to the same content.
Who proposed adding AGENTS.md to the Linux kernel?
Sasha Levin, an engineer at NVIDIA and a known contributor to AI-related kernel tooling discussions, proposed symlinking a top-level AGENTS.md to the kernel’s existing README file on the Linux Kernel Mailing List.
What is the kernel’s existing policy on AI-assisted code?
Other agents ship a demo. Remy ships an app.
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
The kernel documents its stance in Documentation/process/coding-assistance.rst, which the README already references. That document covers things like the required “Assisted-by” attribution tag for AI-assisted contributions, distinct from the human-only “Signed-off-by” tag.
Why did some maintainers reject the proposal outright?
Objections ranged from technical (concerns about increased token usage and whether a generic file fits a codebase as varied as the kernel) to philosophical (opposition to normalizing AI-assisted development in the kernel at all, regardless of implementation).