cant you simply prompt it to read the code and create whatever md you need it to lol what is the point of this
AGENTS.md – Open format for guiding coding agents
51–60 of 398 posts
Re: AGENTS.md – Open format for guiding coding agents
#52The 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. we probably need a tool for this. In any case, I increasingly question the use of an agents file. What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and…
Agree on the need for hierarchical agents.md. I thought that was kind of standard and I am surprised that this proposal doesn’t support that.
Re: AGENTS.md – Open format for guiding coding agents
#53Earlier quoted context omitted.
It is. 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.
Why would these things not be relevant for humans?
They are relevant but dumping it all into one document in the project root isn’t as optimal for humans as it is for agents, especially since a lot of that information is irrelevant to someone landing on your repo, who probably just wants to add it to their dependency manifest or install the app followed by usage instructions geared to humans.
Re: AGENTS.md – Open format for guiding coding agents
#54This should've been an .agents¹ with an index.md. For tiny, throwaway projects, a monolithic .md file is fine. A folder allows more complex projects to use "just enough hierarchy" to provide structure, with index.md as the entry point. Along with top-level universal guidance, it can include an organization guide (easily maintained with the help of LLMs). index.md ├── auth.md ├── performance.md ├── code_quality ├── da…
Been using a similar setup, with so far pretty decent results. With the addition of having a short explanation for each file within index.md
I've been experimenting with having a rules.md file within each directory where I want a certain behavior. Example, let us say I have a directory with different kind of services like realtime-service.ts and queue-service.ts, I then have a rules.md file on the same level as they are.
This lets me scaffold things pretty fast when prompting by just referencing that file. The name is probably not the best tho.
Re: AGENTS.md – Open format for guiding coding agents
#55At this point AGENTS.md is a README.md with enough hype behind it to actually motivate people to populate it with contents. People were too lazy to write docs for other people, but funnily enough are ok with doing it for robots. This situation reminds me a bit of ergonomic handles design. Designed for a few people, preferred by everyone.
I think it’s the reverse - people were too lazy to read the docs so nobody was motivated to write them. 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.
I like this insight. We kind of always knew that we wanted good docs, but they're demotivating to maintain if people aren't reading them. 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.
Re: AGENTS.md – Open format for guiding coding agents
#56Earlier quoted context omitted.
... most of which would also be valuable information to communicate when onboarding new devs.
If there were already a universal convention on where to put that stuff, then probably the agents would have just looked there. But there's not, so it was necessary to invent one.
Reality is just that people neglected onboarding docs until LLM-based coding agents put them in a position to directly benefit from having more knowledge of the codebase explicitly written down.
Re: AGENTS.md – Open format for guiding coding agents
#57So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better?
Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".
Re: AGENTS.md – Open format for guiding coding agents
#58Earlier quoted context omitted.
Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
README often contains only basic context for the project and instructions for basic tasks like running it and building it from source. If additional information for developers, like coding conventions, is short enough compared to the rest of the README then it sometimes gets added there too, but if there's a lot of it then it's frequently kept elsewhere to prevent README from getting overwhelming for end users and ra…
I don't think anything requires a README.md to be monolithic. They often provide the introductory material that you mention here, then link out to other appropriate files for contribution guidelines, etc.
Re: AGENTS.md – Open format for guiding coding agents
#59Yet every agent I use (Claude Code, Gemini and Aider) uses their own custom filename. It would be nice if it was standardized. Right now I’m using ruler to automate generating these files for all standards as a necessary evil, but I don’t envision this problem being solved soon. Especially because these coding agents also use different styles for consuming MCP configs. https://github.com/intellectronica/ruler
Jules uses AGENTS.md, which indicates that Google is on board with it as the standard. If Gemini Code Assist continues to be a thing (I'm not sure whether Jules is intended to succeed it) then presumably it will support AGENTS.md as well. In the meantime you can configure Gemini Code Assist to use an arbitrary filename.
I don't see a reference to a specific filename in Aider's documentation, can you link to it?
Anthropic appears to be the major holdout here.
Re: AGENTS.md – Open format for guiding coding agents
#60Unfortunate that two of the most-used tools (Claude Code, Gemini CLI) don't support it.