AGENTS.md – Open format for guiding coding agents
(agents.md)823 points by ghuntley 5 days ago
823 points by ghuntley 5 days ago
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. 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 again?
Another thought: are folks committing their AGENTS.md? If so, do you feel comfortable with the world knowing that a project was built with the help of AI? If not, how do you durably persist the file?
> do you feel comfortable with the world knowing that a project was built with the help of AI?
I would be deal-breakingly concerned if I thought someone was actively trying to hide the fact from me.
What does "support" for this format mean beyond "reading the file without explicit prompting"?
Like, as the end-user, if I copy-paste "Please see AGENTS.md in the project root for some information on the project" have I filled the gap?
Or is the LLM ingesting this file in some special way I'm losing out on?
>Like, as the end-user, if I copy-paste "Please see AGENTS.md in the project root for some information on the project" have I filled the gap?
Probably, yeah. It would cause an extra tool call at the start of every session, though, so a symlink might be preferable.
wrote this protocol like a month ago :)
Prediction: this means extra work for developers. it also means extra potential abuse and risk through agents. the agents.md will sometimes be outdated or inconsistent with the readme. even the readmes are sometimes outdated or inconsistent with the code. some developers will interpret agents.md as compiling code for the agents to use, not for the user's to use, so maybe you're not even compiling the same code the same way a human should and expectations are broken. it's only a contextual efficiency if it's reliable too, because errors can mean having to use even more context accounting for it.
better idea since agents will already be cursed to do these things:
- any decent readme should have titled sections unless it's small
- if it's small, just feed the entire readme into it
- if it's large, provide it with a list of readme sections and let it choose which ones are relevant.
- also highlight which parts of the markdown include code blocks.
- if all else fails and it's huge without sections, just use RAG.
- if your model runs fast enough, then even if it's huge, just feed the whole thing in so you avoid the risks of RAG. setting up new software can be important enough that you may as well get it right.
people couldn't be hassled to make things accessible to the blind or visually impaired really, why suddenly should they be all excited to make everything accessible to AI? besides, agents.md comes with psychological baggage like, "i'm presuming my project is interesting enough to be used by agents!". just use the readme. it's basically always there and then in most cases you won't have to do 2 requests, you can just do 1.
if "agents.md" is supposed to be anything, it should be a locked file or special URL generated by github for your repo that always mirrors the relevant instructions in the readme so there's some higher reliability. then anyone that specifically wants to improve agents.md can simply follow some conventions in the readme file to make sure understanding is maximized. essentially, a github agent generates agents.md for other agents. if the github agent can't understand the readme well enough to produce an agents.md, what chance would your agent have? if the github agent feels like there are contradictions or confusion, it can automatically report that to the developers so they can sort it out.
besides, github themselves could have motivation to do this if they are destined to be slammed with tons of bot traffic they have no way to sufficiently block. at least this way maybe they can make it more efficient and it becomes another valuable feature of the platform.
If the context is not good for a Llm is also not good for a human. All this magical nonsense that is blooming around AI is tiresome, it needs to stop. Programming is not tarot reading or a slot machine. We cannot leave the security and robustness of our systems into such heuristics.
Markdown is certainly easy for humans to write, but as OpenAI pointed out last week, wouldn’t an XML-based format be easier for LLMs to parse and understand?
https://cdn.openai.com/API/docs/gpt-5-for-coding-cheatsheet....
From OpeAI's last week document for coding with gpt5.
> #3. Use XML-like syntax to help structure instructions
I don't know if GPT-5 is an exception and is overcooked on XML specifically, but in general Markdown and XML seem to work about equally well for LLM inputs, the important part is just that they like hierarchical structured formats. The example on that page could probably be replaced with:
## Code Editing Rules
### Guiding Principles
- Every component should be modular and reusable
...
### Frontend Stack Defaults
- Styling: TailwindCSS
they are just moving goal posts because agents still largely suck for everything except a couple of super saturated problem domains that really shouldn’t require anything special from a dev anyways
opencode made one of these for me when I did an /init in my existing project
I can’ take this seriously, ever since they started talking about llms.txt, thousands of apps spawned promising increasing AI SEO by generating such file. I’ve created one myself for several websites and have seen 0 impact. I guess agents.md will have the same fate.
lol, if the primary outcome is better documentation...i'll take it
Honestly, this is some of the most bizarre shit I’ve ever seen.
The day AI and AI adjacent slop is no longer polluting the front page is the day when some other random fad takes hold I guess.
Make is a command runner, no? It's completely different.
Yes, writing clear examples and instructions for humans was never seen as a good use of time, but as soon as a dumb mutt of an AI needs them to do stuff, they're written, and with more compassion than was ever shown to newbies asking questions...
We've lost a bunch of contributions to open source projects because these guides weren't there to help new people contribute.
This is a sad timeline. "AI is going to replace engineers.. but first please fill this human-readable markdown file to help it understand your code". What a bunch of morons, that's just called documentation.
Instead of using AI where it can actually have positive impact on human lives like medicine, biology, et al. we're wasting huge amounts of resources and generating tons of pollution to teach it to program and steal art and books so Aunt Lily can generate a video of a dog.
> that's just called documentation.
Ironically you sound very optimistic about AI capabilities here. This implies that an AI is just as capable as a human because all they need to contribute is what a human needs to contribute.
Alternatively if you think AI is useless trash then clearly they need more than a human readme to do anything?
Dumb question from a guy who just set up Claude Code for the first time yesterday: would this be the equivalent of `CLAUDE.md` in a project directory?