agentsmd
Clarification: is AGENTS.md intended for coding agents specifically, or agents in general?
I’d like to clarify the scope of this convention.
At present, the wording and examples in AGENTS.md are focused on coding agents (setup, build, test, lint, contribution rules, etc.). That’s a narrow but useful case. But the name "AGENTS.md" suggests something more general, that any kind of agent (deployment, operational, usage, etc.) might consult it.
That raises a couple of questions...
If the intent is coding agents only, would a name like CODING.md or DEVELOPMENT.md be better? That avoids conflating it with non-coding agents. Many repos already have a DEVELOPMENT.md, which is useful to humans too. These are currently more popular than AGENTS.md but don't have the momentum that the current crop of coding agents are bringing to AGENTS.md, so switching now doesn't seem realistic.
If the intent is all agents, then AGENTS.md converges with README.md. Humans and non-coding agents alike already need the same instructions to install, run, or interact with the project.
Arguably, something that is noise to an LLM in README.md is also noise to a human. Something that a human might need to know in README.md might be needed by an agent.
If this is the case, my concern is that we might be solving a short-term problem in a way that creates naming debt and duplication. Though perhaps that's a small price to pay for effective coding agents in 2025.
This reminds me of the days of the early mobile web in the 2000's. For a few years, websites used to have a separate accessible or mobile version with limited functionality. Then gradually technology and mindsets shifted and now people realised that making websites more accessible and functional on different screens benefits everyone. AGENTS.md seems like the m. version of a website.
Would love to hear how you see this evolving.
IMO the AGENTS.md could act as the directory and provide details about how and where other specific instructions are present, something like it could conatin an instruction like coding specific instructions can be found at @CODING.md, since the LLM it self does not have the coding of a coding agent or document writer agent and usually introduced by agentic tools like roocode, it would be better the AGENTS.md standards does not expect a CODING.md to be present.
More of a discussion than an issue, but FWIW I agree that AI instructions should converge with those for humans. The last thing I need is another specification to maintain and, more philosophically, surely the point of AI is to allow human-like interaction? Otherwise all we have is another kind of DSL to invent/learn.
