Article

What Is AGENTS.md? The Tiny File Teaching AI Agents Your Rules — and Why the Linux Kernel Wants One

What Is AGENTS.md? The Tiny File Teaching AI Agents Your Rules — and Why the Linux Kernel Wants One

Your newest contributor has read every line of your code and understands none of your conventions. It doesn't know the build command, the test suite, or the unspoken rules about where new code belongs. It's an AI coding agent — fast, tireless, and completely unaware of the context your team carries in its heads.

The fix the industry settled on is almost comically low-tech: a Markdown file called AGENTS.md sitting at the root of your repository. The official format site, agents.md, frames it as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." READMEs are for humans; AGENTS.md carries the extra context agents need — build steps, tests, and conventions — that would clutter human documentation.

The idea has traveled further than most conventions get to. In September 2026, Linux kernel developer Sasha Levin proposed adding an AGENTS.md to the kernel source tree itself, after tests reportedly showed AI agents misbehaving without one. If a plain-text instruction file is worth debating for the world's most scrutinized codebase, it's worth understanding for yours.

What actually goes inside

Per the format's own site, "AGENTS.md is just standard Markdown. Use any headings you like." There is no schema, no required fields, no frontmatter standard — the only real convention is the filename and where it lives. What belongs in it is the stuff that stays true across the whole repository: how to build and test, how directories are laid out, the conventions your team follows, and the mistakes an agent would otherwise make twice. What doesn't belong is anything that goes stale in a week — a file full of outdated commands is worse than no file, because the agent believes it.

Two mechanics matter in practice:

  • Nested files. In large repositories you can add an AGENTS.md per subproject; the closest file in the directory tree takes precedence, so frontend rules don't pollute a backend task.
  • Precedence. Explicit instructions you give in chat override the file. The file is the default, not the law.

The format is also intentionally one file instead of many. Before it existed, every tool invented its own path — .cursorrules, .github/copilot-instructions.md, CLAUDE.md, .aider.conf.yml — and repositories accumulated near-duplicate instruction files that drifted out of sync. The open format, stewarded by the Agentic AI Foundation under the Linux Foundation, gave everyone a shared target: the foundation's announcement cites adoption by more than 60,000 open-source projects, and readers now include OpenAI Codex, Cursor, GitHub Copilot's coding agent, goose, Gemini CLI, Zed, Aider, Jules, Devin, and Windsurf, among others. (Claude Code is the notable holdout by default — it reads CLAUDE.md, and the documented move is to have CLAUDE.md import AGENTS.md.)

The kernel's agent problem

Why would the Linux kernel — a project with famously thorough human documentation — need an instruction file for robots? Because agents keep tripping over rules that humans absorb by osmosis.

The kernel's official policy on AI contributions lives at Documentation/process/coding-assistants.rst (published at docs.kernel.org), and it's remarkably direct:

AI agents MUST NOT add Signed-off-by tags. Only humans can legally certify the Developer Certificate of Origin (DCO).

The Signed-off-by line is the legal backbone of kernel contributions — a human certifying they have the right to submit the code. An agent generating that line is a human claiming responsibility for work they may not have reviewed. Instead, the policy requires contributions to carry an Assisted-by tag:

Assisted-by: LLM coccinelle sparse

That much is verified from the kernel's own documentation, so it's stated as fact. Everything around the proposal itself comes from press coverage of the mailing-list discussion, which deserves a grain of salt.

The backstory, as reported: Sasha Levin, a longtime kernel developer and Linux LTS co-maintainer, floated a broader RFC proposing unified config files for tools like Claude, Cursor, and Copilot, funneled into central documentation demanding kernel coding standards, proper attribution, and an understanding of the development process. The attribution requirement itself became a fight — developer Christian Brauner reportedly called the disclosure tags irritating, arguing they turned git history into "a free advertising platform" for AI companies, and proposed dropping the mandate. Meanwhile Greg Kroah-Hartman moved to reject LLM-generated patches in the staging area except for genuine security fixes, worried the flood of automated contributions would overwhelm human reviewers. And Linus Torvalds, for his part, has said AI is just a tool — "clearly a useful one" — and that "Linux is not one of those anti-AI projects" (per TechNews's report of the kernel mailing list). The kernel isn't anti-agent; it's pro-rules.

The kernel's AGENTS.md is deliberately tiny

Which brings us back to Levin's September 2026 proposal, reported by Phoronix: add an AGENTS.md to the kernel source tree — but keep it minimal. Rather than duplicating the kernel's enormous process documentation, the proposed file simply links to the kernel's README and the coding-assistants documentation, pointing agents at the rules instead of restating them.

The rationale, per the reports, was test-driven: without the file, one tested agent added an unauthorized Signed-off-by line to a proposed patch and used its own invented attribution tag instead of the kernel's standardized Assisted-by; a second agent added no attribution at all. With the AGENTS.md in place, both agents reportedly behaved closer to kernel requirements. Objections reportedly focused on token cost — pointing every agent at the full README means burning a lot of context on instructions — which is the honest tradeoff of the whole convention: instruction files are loaded eagerly and paid for every session.

For a project at the kernel's scale, even the placement of a text file is an architectural decision. For the rest of us, it's a free lesson: if your project is too big for one instruction file, link out to the docs that already exist instead of copying them.

Steal the pattern for your own repo

You don't need to be the Linux kernel to benefit. The format's guidance suggests covering project overview, build and test commands, code style, testing instructions, security considerations, and commit/PR conventions. A minimal starter looks like this:

# Project name

## Build
npm run build        # must pass before any PR
npm test             # full suite, ~4 min

## Conventions
- TypeScript strict; no `any` without a comment explaining why
- API handlers live in src/routes/, never in src/lib/
- Commits: imperative mood, max 72 chars

## Never do this
- Do not edit generated files in dist/
- Do not add dependencies without asking first

You don't have to write it by hand, either — most agents can draft one from your codebase (several tools offer an /init command for exactly this), and your job is to correct it. Review it like code: every line is an instruction you'll pay for, token-wise, in every future session.

This is also where the heavier machinery fits in: if you're building multi-step agent workflows with their own prompts and scripts, agent skills are the next layer up, while AGENTS.md is the standing context they operate within. (See our piece on agent skills for disciplined AI development.) And if you're deciding when the agent should act versus ask first, that's a separate design question — the plan-mode debate is a good companion read.

Instructions, not insurance

The most important thing to understand about AGENTS.md is what it can't do. The kernel's document spells it out: the human submitter reviews all AI-generated code, adds their own Signed-off-by, and takes full responsibility. No instruction file transfers accountability.

What the file does is make the implicit explicit. Every team has rules that live in senior engineers' heads — which tests matter, which directories are sacred, what "done" looks like. Writing them down for an agent turns out to write them down for everyone: new hires, future you, and the next contributor who reads every line of code but none of the conventions. The kernel debating a 20-line Markdown file is really debating the oldest question in software: how do you teach a new worker the rules of the workshop? The answer, it turns out, fits in a text file.

Keep reading
Pi Hits 1.0 and Launches pi-durable: What's an Agent Runtime, Really?
Read next →