AGENTS.md – Open format for guiding coding agents

This discussion revolves around the emergence and standardization of a .md file, specifically AGENTS.md, intended for LLM agents to use as a set of instructions and context about a codebase. The core debate is whether this separation is necessary and beneficial, or if such information should remain integrated within existing documentation like README.md or CONTRIBUTING.md.

Here's a breakdown of the key themes:

Separation of Concerns: Human vs. Agent Guidance

A central argument for a dedicated AGENTS.md file is the need to differentiate information and instructions tailored for AI agents from content meant for human readers.

For Separation: "README is for humans, AGENTS / etc is for LLMs. Document how to use and install your tool in the readme. Document how to compile, test, architecture decisions, coding standards, repository structure etc in the agents doc." (stingraycharles) This view posits that human-readable marketing or basic usage information in a README.md might be noisy or even condescending for an AI, and vice-versa. Specific instructions that correct egregious AI patterns, like "never write fallback code," are seen as too specific for a general human audience. (furyofantares)
Against Separation: Some argue that everything intended for an agent should ideally be present in a well-structured README.md. "Everything in the AGENTS.md file should just be in a good README.md file." (blinkymach12) Others feel that specific coding advice, like not running the whole test suite due to slowness, is beneficial for humans to see in the README.md as well. "For most development we recommend running single/specific tests since the whole suite is slow/expensive." sounds like a great thing to put in the readme. (viraptor)

The Nature of Instructions: Special vs. General Guidance

The discussion touches on whether the instructions provided in an AGENTS.md file are fundamentally different or are simply more detailed versions of what humans would need for onboarding or contributing.

Agent-Specific Instructions: It's argued that agents might require very specific, sometimes blunt or imperative, instructions that wouldn't be suitable for human communication. "Some of it I don't even mean, it's just there to correct egregious patterns the model loves to do." (furyofantares) Examples include specific file naming conventions (.spec.ts vs. .test.ts) or guidance on managing context to avoid overwhelming the agent. (petesergeant)
Human-Readable Instructions: Many believe that what benefits an agent also benefits a human contributor. "This applies to mcp too" (TZubiri, likely referring to similar agent context management). Proponents of this view feel that information about build processes, testing strategies, or architectural decisions should be accessible to both humans and AI. "That seems exactly like something you would want to tell another developer" (ecb_penguin) in response to advice about test suite usage.

Context Management and Efficiency for LLMs

A significant motivation for a separate file is the desire to efficiently manage the context window provided to LLMs, to avoid unnecessary tokens and improve performance or accuracy.

Conciseness for Context: "Less is generally better and README.md files are often too much text some of which I don’t want in every context window." (trailrunner46) The idea is to provide precise, lean instructions to LLMs, especially crucial when dealing with API costs or token limits. "In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality." (from an linked article, quoted by kaycebasques)
Avoiding Noise: Information irrelevant to the current task or context for the agent should be excluded. "Because managing an AI’s context is important and you don’t want to put stuff in there that’s not relevant." (stingraycharles)

Standardization and Convention

A major driver for AGENTS.md is the perceived need for standardization across different AI coding tools, which currently use various filenames for agent instructions.

The Need for a Standard: "All the different coding agents put their "rules" in different places: .cursor, CLAUDE.md etc. . It makes no sense and it really needs standardisation." (arrowsmith) Many users express a desire for a unified naming convention to simplify adoption and tool integration. "It would be nice if it was standardized." (stingraycharles)
Analogy to Existing Conventions: The emergence of AGENTS.md is compared to universally accepted files like .gitignore, CONTRIBUTING.md, and LICENSE. "Standards derive their value precisely from being simple and widely adopted - think of .gitignore, CONTRIBUTING.md, or LICENSE files that work because everyone agrees on their location and purpose." (ethan_smith)
Counterarguments to Standardization: Some challenge the notion that these existing files are true standards, noting that they are conventions or formats specific to certain platforms or tools. ".gitignore is not a standard: it’s a format used by one tool." (chrismorgan)
Platform Adoption: Google's adoption of AGENTS.md through tools like Jules is seen as a positive step towards standardization. "Jules uses AGENTS.md, which indicates that Google is on board with it as the standard." (ameliaquining)
Vendor Lock-in Concerns: A more cynical view suggests that the push for a specific filename might be an attempt by vendors to create lock-in rather than genuine standardization. "My (slightly cynical) take is that they're trying to create whatever vendor lock-in they can, so standardization feels hits a bit too close to commoditization" (conradkay).

The Role of `CONTRIBUTING.md`

Several users propose that CONTRIBUTING.md is a suitable, existing convention that could serve the purpose of agent instructions, or that AGENTS.md instructions could be symlinked to it.

CONTRIBUTING.md as a Precedent: "We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?" (crazylogger) The argument is that this file already exists to guide external contributors, and AI agents can be viewed as a type of contributor.
Hybrid Approach: A suggestion is to leverage CONTRIBUTING.md and allow contributors (human or AI) to symlink their preferred agent-specific configuration to it. "My current thought is that (human) contributors should be encouraged to ln -s CONTRIBUTING.md CLAUDE.local.md or whatever in their local checkout for their agent of choice..." (andyferris)

Motivation for Documentation

The advent of AI agents is seen by some as a catalyst for better and more consistently maintained documentation, which was often neglected.

AI as a Driver for Docs: "People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots." (spawarotti) If agents are actively reading and acting upon documentation, it provides a tangible incentive to create and maintain it. "With an agent I know if I write once to CLAUDE.md and it will be read by 1000’s of agents in a week." (nicklo)
Validation of Documentation: "LLMs by their nature won't be onboarded to the codebase with meetings and conversations, so if we want them to have a proper onboarding then we're forced to be less lazy with our docs, and we get the validation of knowing they're being used." (blinkymach12)

Hierarchy and Structure

The discussion also explores the potential for structured and hierarchical documentation, rather than a single, flat AGENTS.md file.

Nested AGENTS.md: Some systems support placing AGENTS.md files in subdirectories, allowing for more granular context. "...the main OpenAI repo has 88 AGENTS.md files." (quoted by neuronexmachina)
Against Flat Files: Concerns are raised about the limitations of a single file, particularly for large or complex projects, advocating for a more organized structure. "The agents instructions file needs to be hierarchical; It's a pain managing multiple agents.md files with a lot of duplication between them for different projects, even in a mono-repo." (prmph)
Alternative Structures: Suggestions include using indexed directories or a main index.md file within a hidden .agents or .codebots directory to manage various agent-specific instructions. "This should've been an .agents¹ with an index.md." (CharlesW)

Future of Agent Interaction and Documentation

The conversation speculates on how LLM interaction with codebases will evolve, and how documentation formats might adapt.

Transition Phase: "We're in a transition phase today where agents need special guidance to understand a codebase that go beyond what humans need. Before long, I don't think they will." (blinkymach12) This implies that current needs for explicit agent instructions might diminish as LLMs become more broadly capable.
Machine-Readable Practices: Similar to autonomous driving needing machine-readable traffic laws, codebases might increasingly adopt machine-readable practices. "I suspect machine readable practices will become standard as AI is incorporated more into society." (goosejuice)
XML vs. Markdown: A thought is raised that XML might be a more parseable format for LLMs than Markdown. "wouldn’t an XML-based format be easier for LLMs to parse and understand?" (ekusiadadus)
Transparency and AI Usage: There's a question about whether projects should be transparent about their use of AI in development, and how this relates to committing AGENTS.md files. "If so, do you feel comfortable with the world knowing that a project was built with the help of AI?" (prmph)