[Question] Help me understand why this exists

[jorisw]

README.md files are for humans: quick starts, project descriptions, and contribution guidelines.

Why wouldn't this information be useful to agents?

AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.

Why would clear and concise build steps be more useful to agents than to humans?

Why would clutter not hurt humans?

We intentionally kept it separate to:

Give agents a clear, predictable place for instructions.

As a human, I too want instructions in a clear, predictable place. That's README.md.

Keep READMEs concise and focused on human contributors.

Why is concise information uniquely valuable to human contributors? What's the difference between agents and human contributors when it comes to preferring a high signal, low noise README ?

Provide precise, agent-focused guidance that complements existing README and docs.

What about good guidance is agent-focused?

A good README is concise while complete, and should service humans and agents the same way. Aren't LLMs trained on human writing?

This project reminds me of the times that Search Engine Optimization was thought to mean something other than just having a well structured site with lots of useful content. There's a reason Search Engines have switched to regular browsers for crawling sites: websites need to be written for people. Search engines rank sites based on that.

I strongly believe AGENTS.md discourages writing and maintaining good README.mds.

[dannysmith]

This is just a standard naming convention for the files AI coding harnesses have always used for this: CLAUDE.md, GEMINI.md and the like.

While I agree that most AGENTS.md should probably contain most of what's in a good README.md, the inverse is not at all true, and human-facing docs should be optimised for the stuff humans need while llm-facing docs should be optimised for what they need (and token efficiency etc)

I've seen a lot of README's optimised for LLMs and they're horrible to read.

[DimaKH]

@jorisw here are three scenarios that came to my mind to illustrate where the distinction matters:

1. Small Internal Repo: I agree with you here. In this context, AGENTS.md often ends up being just a redundant copy of the README.

2. Public Repo:

   • README: For human users(marketing, high-level features, links to public docs).
   • AGENTS.md: For AI contributors. This file can focus on internal architecture, local setup commands, and strict testing/linting/PR rules required to maintain the codebase.

3. Same as scenario 2 + you want to provide up-to-date context and instructions to customer's AI agents using your SDK/framework. This creates a potential conflict regarding the target audience for AGENTS.md (I describe the details in this ISSUE).

Why not just use the README here? If you look at complex SDKs like Flutter, the README is full of badges, images, and links. This is noise to an llm. Since most agents have limited context windows and skip external links in README, you would like to optimize it. In this case, keep the README for humans, but treat CONTEXT.md (or AGENTS.md) as a Zero-Config RAG for agents. You can provide there strictly technical information, optimized for token efficiency rather than human readability.