LLVM Opens the AGENTS.md Debate, and Nobody Agrees Yet

A Markdown file at the root of a repository, telling an AI agent the house rules: that’s all AGENTS.md is. Plenty of open source projects already carry one, and the matter is usually settled in a single pull request. Not at LLVM. The discussion opened on 2 September 2026 on the project’s Discourse by Nick Desaulniers, a long-time LLVM developer, got a reception that Phoronix, reporting on it on 3 September, sums up in one word: mixed.

The file that says hello to the agents

The idea is a modest one. Rather than let every AI agent guess a project’s conventions, you write them down in plain sight. Desaulniers even opened a draft pull request with a bare-bones version: it does nothing but point the agent at LLVM’s documentation on the AI tooling contribution policy, and at the coding standards. Nothing else. No recipe, no secret prompt — just a signpost.

The proposal also mentions a CLAUDE.md, the variant specific to one particular assistant. Which raises, in passing, the question of how many files like this a repository root can take on before it starts to look like a fridge door under a landslide of magnets.

The noise camp and the principle camp

Some developers are in favour. Others reckon these files mostly generate noise, with no demonstrated benefit — an argument you rarely hear put this calmly in a discussion about AI.

The most interesting objection sits elsewhere: hosting such a file would cut against a principle LLVM already holds to, namely not pushing one developer’s private workflow into the repository. An AGENTS.md isn’t technical documentation, it’s a tool setting. And a project’s repository has never traditionally been the drawer where you keep your editor preferences. The argument is reinforced by a detail raised in the thread: several contributors already run their own AGENTS.md material, in their private repositories. The need is real — it’s simply being met somewhere else already.

Project size, a very concrete obstacle

On top of that comes a difficulty with nothing philosophical about it: LLVM isn’t a project, it’s a bundle of sub-projects with different remits. A single file at the root would speak on behalf of all of them, with all the precision you’d expect from that. One file per sub-project would multiply the documents to keep current — and an instruction file that has gone stale doesn’t make the agent neutral, it makes it confident and wrong.

That is probably why the proposed version is minimal to the point of holding almost no content of its own: it doesn’t say how to contribute, it says where that’s written down. It’s hard to be more cautious than that.

What the debate is actually testing

Behind the file, the real question put to LLVM is one of hospitality: how far does an infrastructure project of this size want to smooth the path for contributors who don’t read the documentation but swallow the repository whole. No position had been settled as of 3 September 2026, and there’s nothing to suggest one will be soon.

And yet the version on the table amounts to politely asking the agent to go read the docs. If even that can’t win a consensus, the argument was never about the file.