Linux Kernel AGENTS.md Proposal Tests Whether AI Agents Can Follow Human Rules

The Linux kernel AGENTS.md proposal adds only one symbolic link, yet it targets a growing conflict over AI-assisted code. Submitted on September 24, 2026, the patch would make the kernel’s existing instructions easier for coding agents to find automatically.

The proposed file would not authorize autonomous contributions or relax the kernel’s review standards. It would point agents toward a README that already directs AI tools to the project’s detailed contribution policy. The change addresses a narrower problem: agents often act before reading documentation written primarily for people.

That distinction matters because the kernel already tells AI tools not to certify patches on a person’s behalf. It also requires human review, proper attribution, testing, and responsibility. The Linux kernel AGENTS.md proposal therefore pits discoverable instructions against a harder reality: a repository file can guide an agent, but it cannot make an unreliable patch trustworthy.

The Linux Kernel AGENTS.md Proposal Changes One Entry Point

The patch changes how agents discover existing rules, not the rules themselves.

Kernel maintainer Sasha Levin submitted a patch titled “docs: add AGENTS.md as a symlink to README.” The proposal creates a top-level symbolic link named AGENTS.md, which points to the repository’s existing README file.

A symbolic link is a filesystem reference that redirects one filename to another file. In this case, an agent opening AGENTS.md would receive the same material already available through README, rather than a second copy of the instructions.

That design avoids creating two policy documents that maintainers would need to synchronize. Levin’s symlink proposal says the existing README already directs AI tools to Documentation/process/coding-assistants.rst. The problem is that an agent must decide to open the README before that pointer helps.

Many coding agents inspect specially named instruction files automatically. AGENTS.md has become one of the common filenames for repository-level directions, including build commands, testing requirements, coding conventions, and safety boundaries.

The proposed kernel file would contain no separate prose. Its only content would be the link target, README. That keeps the human and machine entry paths attached to one maintained source.

Levin included a controlled example to explain why discoverability matters. Two agents received the same request: create a commit that renamed the kernel release in the Makefile to “AI Test.”

Without AGENTS.md, one agent generated a Signed-off-by line for the user. The other supplied no AI attribution. Both results conflicted with the kernel’s documented expectations.

With the symlink present, both agents reportedly used an Assisted-by: LLM tag and avoided adding a human signature. They also followed the project’s commit-message conventions more closely. One added a descriptive body, while the other used the expected “subsystem: summary phrase” subject structure.

This was a limited behavioral test, not a broad evaluation of agent reliability. It did not measure whether agents could find subtle bugs, produce safe fixes, or understand subsystem-specific constraints. It showed that two agents behaved differently after receiving an automatically discovered route to existing instructions.

The change was still under review when reported. Describing it as something Linux has already adopted would therefore overstate the event. The accurate claim is that a kernel maintainer proposed the link and supplied evidence supporting it.

Kees Cook, a prominent kernel security developer, responded with an acknowledgment. He supported using the README instead of maintaining a separate agent-only policy. His review response also noted that having agents read contribution documentation before creating patches would be desirable.

The patch is tiny enough to look ceremonial. Its practical purpose is concrete, however. It tries to put mandatory process information on the path an AI tool is already trained or configured to inspect.

That makes the proposal an interface change. Humans can browse documentation trees and interpret community norms. Coding agents work more predictably when repositories expose those norms through filenames and paths the tools recognize.

The resulting question is not whether Markdown can improve generated code. It is whether a dependable entry point can prevent recurring process errors before maintainers must catch them manually.

Existing Kernel Rules Still Put Humans on the Hook

The Linux kernel’s AI policy treats an agent as an assistant, never as the legal or technical owner of a contribution.

The underlying rules already go much further than the proposed symlink. The kernel’s AI contribution guide directs AI tools and their users through the standard development process, coding style, patch-submission requirements, licensing rules, and generated-content policy.

Most importantly, the guide says AI agents must not add a Signed-off-by tag. That line is not decorative commit metadata. It represents a person’s certification under the Developer Certificate of Origin, commonly called the DCO.

The DCO is the mechanism through which a contributor states that the submitted work can legally enter the project under its license. A language model cannot make that certification for a person. It also cannot determine whether the person completed the review necessary to accept responsibility.

The human submitter must review the generated code, confirm licensing compliance, add the signature, and take responsibility for the contribution. An agent that inserts the signature itself collapses those separate steps into generated text.

That is why Levin’s test matters despite its small scope. The agent did not merely choose an unpopular formatting style. It generated a statement that only a human can legitimately make.

The kernel’s documentation assigns AI participation a different marker. When an AI tool contributes, the patch should use an Assisted-by tag. Optional analysis tools such as Coccinelle, Sparse, Smatch, or Clang-Tidy can also appear after the LLM label.

This attribution model distinguishes assistance from authorship and certification. It gives reviewers useful context without pretending the model can assume responsibility.

The documentation also establishes a demanding process for AI-assisted bug work. An agent should read the complete relevant documentation, locate a specific bug, and attempt to reproduce any nontrivial issue. It should abandon a finding that does not survive verification.

If the issue appears real, the agent should write a fix, build it, test it against the reproducer or a complete analysis, and run the kernel’s patch checks. It must state anything it could not verify.

The guide further tells the agent to identify the relevant maintainers and mailing lists. It must assess whether the issue belongs in the regular bug process or the confidential security process. The agent must leave actual submission to the person using it.

Those requirements expose the limits of treating AGENTS.md as a solution by itself. The file can route an agent to the correct checklist. It cannot confirm that a reproducer is meaningful, testing is sufficient, or the human understands the code.

Kernel development also spans thousands of components with specialized expectations. General instructions cannot contain every architectural constraint, hardware assumption, or maintainer preference.

An agent might comply perfectly with the visible formatting rules and still misunderstand lifetime management, locking, memory ordering, or device behavior. A polished commit message can make such a patch easier to review, but it does not make the underlying reasoning correct.

That creates a useful boundary. Repository instructions can reduce avoidable administrative mistakes. Technical confidence still has to come from evidence, tests, expert review, and accountable contributors.

For maintainers, that separation is important. Every malformed submission consumes attention before anyone reaches its technical substance. Better instruction discovery can lower that overhead without lowering the acceptance bar.

For contributors, the policy is equally clear. Using an agent does not transfer responsibility. A developer must be able to explain and defend the result as if every line had been written manually.

Why AI Coding Agents Keep Missing the README

The conflict is between documentation that exists and instructions that appear inside an agent’s automatic context.

Repositories traditionally organize their contributor information for people. A README introduces the project, while contribution files, documentation directories, mailing-list pages, and scripts hold more specialized procedures.

A person arriving at the Linux source tree can follow that hierarchy. An agent receiving a narrow prompt may instead inspect only the files it considers immediately relevant. If it never opens the root README, the README’s link to the AI policy remains invisible.

That behavior appeared in a recent kernel discussion about an AI-assisted Qualcomm I2C fix. A maintainer observed that the process was documented through a chain starting in the README and continuing into coding-assistants.rst. Yet tools did not reliably follow that chain.

The maintainer discussion raised the lack of an AGENTS.md or CLAUDE.md file that common tools inspect by default. It also cautioned that adding such a file would not necessarily solve everything.

This is the pressure behind the new proposal. Kernel maintainers face AI-assisted patches whether or not the repository optimizes its documentation for agents. Refusing to add an entry point does not stop contributors from using those tools.

The practical choice is narrower. Maintainers can leave agents to discover human-oriented documentation inconsistently, or place a familiar signpost in the repository root.

The broader AGENTS.md convention describes the file as a README for agents. Its open-format documentation says more than 60,000 open-source projects use the convention, although that figure reflects indexed examples rather than an audited measure of active agent use.

The format imposes no required schema. A project can list setup commands, code-style rules, tests, security concerns, or links to deeper documentation. Nested files can provide more specific instructions for subdirectories.

That flexibility helps explain why the format has spread. A repository can use one plain Markdown file across several tools without committing to a proprietary configuration system.

The kernel proposal uses an unusually conservative version of that pattern. It would not create a large agent manual or repeat information already maintained elsewhere. It would expose the existing README under a name agents are likely to request.

This approach also preserves parity between human and machine guidance. Kees Cook said the README was intentionally designed to work for agents. Linking to it reinforces that shared path rather than creating a private set of rules that human contributors might never see.

A shared source reduces policy drift. If maintainers update the README or its pointer to the AI guide, agents receive the change through the symlink. A copied AGENTS.md could silently become outdated.

Still, the use of a symlink introduces a compatibility consideration. Unix-like systems handle repository symlinks naturally, but some Windows configurations check them out as ordinary files. An agent could then see the word README rather than the referenced content.

That does not invalidate the proposal, especially for a project developed primarily through established Linux workflows. It does show why the patch must be evaluated as infrastructure rather than magic metadata.

Tool behavior also varies. Some agents automatically load AGENTS.md, while others prefer tool-specific filenames or require explicit configuration. A universal-looking filename does not guarantee universal ingestion.

The patch therefore improves the likely path for many agents without eliminating tool differences. Its benefit depends on the client following the link, respecting the instructions, and preserving them throughout the task.

Those conditions are stronger than simply having good documentation. They are weaker than an enforceable technical control.

Better Instructions Do Not Make Generated Patches Safe

AGENTS.md can improve compliance, but it cannot establish correctness, provenance, or genuine human review.

The strongest argument for the proposal is operational. Agents are already producing kernel-related patches, so maintainers should give them a predictable route to the rules. Preventing bad signatures and missing attribution saves review time.

The strongest criticism is also operational. A generated patch can follow every visible instruction and remain wrong in ways that are difficult to detect.

Instruction-following evaluations often use simple, observable outcomes. Did the agent add the right tag? Did it run a named command? Did it format a subject correctly? Those checks matter, but kernel quality depends on deeper properties.

A fix can pass compilation and still introduce a race. A reproducer can exercise one hardware configuration while missing another. An agent can cite the right documentation while misunderstanding the invariant that documentation assumes contributors already know.

There is also a risk that cleaner presentation increases misplaced trust. A well-structured commit message, valid attribution, and passing checks can make an AI-assisted patch look mature. Reviewers must still treat those signals as process compliance, not proof of technical soundness.

The kernel’s current policy anticipates that problem. It requires a human to review the code and take responsibility. It also asks contributors to disclose missing tests or unsuccessful verification instead of hiding gaps behind confident prose.

Whether people will follow those requirements is outside the reach of AGENTS.md. A contributor can remove an attribution tag, ignore a failed test, or submit code they do not understand. The file has no independent mechanism for confirming the human review occurred.

Other open-source projects have responded to the same problem with different strategies. The linux-firmware repository adopted agent-focused documentation earlier in 2026, including contribution rules and attribution guidance. Its firmware guidance offered a nearby precedent for agent-readable policy.

NetworkManager took a more adversarial approach after establishing its AI policy. Its instructions reportedly told noncompliant agents to place an unusual canary word in contributor communications. Maintainers could then detect submissions that followed the hidden instruction while bypassing the project’s policy.

That canary mechanism illustrates the opposite use of an instruction file. Instead of helping an agent produce an acceptable patch, the file helps identify automated behavior that should trigger rejection.

Both approaches recognize the same fact: agents read repository context and change their output accordingly. They differ on whether that behavior should be guided toward compliance or used as a detection signal.

The kernel proposal chooses guidance. It assumes that contributors using agents can still participate if they follow the same legal, technical, and review obligations as everyone else.

That is not an endorsement of unsupervised kernel development. It is an attempt to make the existing boundary visible at the moment an agent starts working.

The proposal also avoids creating instructions that exist only for machines. Because AGENTS.md would point to the README, maintainers and contributors can inspect the same source the agent receives.

Transparency helps, but it does not address prompt injection or malicious repository content. Coding agents routinely consume instructions from files, issue text, comments, logs, and external pages. Conflicting or hostile directions can compete with trusted policy.

A top-level file can establish priority for cooperative tools. It cannot guarantee that every tool applies that priority correctly, especially when the agent reads deeper files containing contradictory language.

There is a related maintenance risk. Any repository guidance can become stale as workflows change. The proposed symlink limits duplication, yet the linked documents still need active review.

The kernel’s scale makes that maintenance especially important. Instructions that are broadly correct can still be incomplete for a particular subsystem. Agents and contributors must continue consulting local documentation, maintainers, build systems, and test infrastructure.

The measured view is therefore neither “AGENTS.md fixes AI code” nor “the file is meaningless.” It can reduce a specific class of predictable errors while leaving the hardest verification work untouched.

That modest claim is supported by Levin’s example. Anything broader awaits evidence from real contributions across varied subsystems and tools.

What Happens Next Will Matter More Than the Symlink

The proposal should be judged by review outcomes, agent behavior, and maintainer workload after adoption.

The first signal is the patch’s disposition. An acknowledgment supports the design, but the change still needs to travel through the kernel documentation process and reach the main repository before it becomes standard project infrastructure.

Reviewers might accept the symlink unchanged, request a regular file, ask for compatibility adjustments, or decide the README route is insufficient. Each result would clarify how the kernel wants to expose rules to automated tools.

The second signal is whether major coding agents consistently follow the link. Levin’s two-agent comparison is useful but small. Wider testing should cover different tools, prompts, working directories, and contribution types.

A successful implementation would produce fewer generated signatures, more consistent Assisted-by tags, better commit subjects, and clearer disclosure of untested work. Those are observable process improvements.

Failure would look different. Agents might ignore the symlink, read only part of the linked material, or follow generic rules while missing subsystem-specific requirements. Tool-specific instruction files might remain necessary.

The third and most important signal is maintainer workload. If the file reduces repetitive corrections without increasing low-quality submissions, it will have served a practical purpose.

If polished agent output encourages more contributors to send patches they cannot explain, the link might improve presentation while worsening the review burden. That outcome would weaken the proposal’s underlying bet.

Maintainers should also watch whether contributors use attribution honestly. The Assisted-by convention only provides value when people preserve it. Automated compliance during generation cannot prevent someone from editing the commit before submission.

Projects beyond Linux will study the result. The kernel is one of the most visible and demanding collaborative codebases, so its treatment of agent instructions carries symbolic weight even when the patch is technically tiny.

That influence should not be confused with a universal policy. Smaller repositories, commercial teams, and projects with different risk profiles may choose fuller instruction files, tool-specific configurations, automated gates, or bans on certain generated contributions.

The kernel’s approach is notable because it does not build a parallel development process. It points agents back toward the process that already governs people.

For engineering teams, the immediate lesson is to separate discoverability from authority. Agent-readable context can identify the correct commands and constraints. Tests, reviews, ownership, and approval systems must still enforce the work.

Teams documenting those boundaries can also keep technical context searchable through an engineering knowledge base. The key is to expose one maintained source instead of copying rules across several agent files.

Over the next several months, watch the patch history, real AI-assisted submissions, and maintainer responses. Those signals will show whether Linux kernel AGENTS.md guidance removes avoidable noise or merely standardizes how that noise arrives.

Repository maintainers should ask a similarly concrete question: which repeated agent mistake comes from missing context, and which one requires an enforceable control? Put stable guidance where tools will find it, then measure whether behavior changes. Keep human review responsible for everything a Markdown file cannot prove.