AGENTS.md – Open format for guiding coding agents
agents.md749 points by ghuntley 19 hours ago
749 points by ghuntley 19 hours ago
This 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
├── data_layer
├── testing
└── etc
¹ Ideally with a better name than ".agents", like ".codebots" or ".context".
This should have been CONTRIBUTING.md all along.
The content of the AGENTS.md is the same as what humans are looking for when contributing to a project.
The most effective argument I have for getting other developers to comment their code is "The agent will read it and it will give better suggestions".
Truly perverse, but it works.
I agree with you... but the reality is that there's a wide contingent of people that are not capable of understanding "people don't know the same things as me". So they need some other reason.
It's made my project documentation so much better. If I write out really good acceptance criteria, 9 times out of 10 I can point Claude at the ticket and get a workable (if unpolished) solution with little to no supervision.
They understand it just fine; they are acting selfishly, because it does not benefit them. Helping the coding agent does.
They really might not understand it fully. That's very much in line with my understanding of how autism works.
several ironies here:
1) an AI agent is less likely to notice than even a junior is when the docs are out of date from the code
2) AI boosters are always talking about using language models to understand code, but apparently they need the code explained inline? are we AGI yet?
3) I frequently hear how great AI is at writing comments! But it needs comments to better understand the code? So I guess to enable agentic coding you also have to review all the agents' comments in addition to the code in order to prevent drift
HOW IS ANY OF THIS SAVING ME TIME
I don’t think they serve the same purpose. Most of the instructions I have for an agent won’t apply to a human. It’s mostly around the the requirements to bootstrap the project vs what I’d ask for a human to accept their pull request.
I think semantically this is true, but the way humans and agents handle context, at the moment, is different enough to warrant a separate structure.
Yeah I can't find any example in an AGENTS.md that isn't useful information for a human. "Cluttering" a README.md is a silly justification.
Nah, My standard for what I write for humans is 100x than the slop I spew for robots.
Also, you don’t even address their point.
Except not hidden. Why do people want to hide important files and directories? Particularly documentation? Tradition, I guess, but it's an antipattern that makes everything more opaque.
Maybe robot_docs?
It's so it doesn't clash with any project that actually has a functional `agents/` directory
Another reason to use a src/ directory for the actual source code.
These files also generally work in a nested fashion, like .gitignore and the like. So you want something that can be injected into the namespace of any directory in your project with relatively low likelihood of conflicts.
Not exactly (or unclear), .gitignore files combine, much like copilot files with glob or other matching. All the instructions are put into the context
> Agents automatically read the nearest file in the directory tree, so the closest one takes precedence
That won't save you if you want actual example.com/agents/foo routing and an (say, real estate) agents list at example.com/agents.
I feel bad that you're getting downvotes. The reason is that pretty much every modern web stack decouples the URL routing from the source code directory structure these days. It was a nice hack back in the day, but there are so many problems with it no one really does it any more.
Some frameworks (Laravel, NextJS, etc) map from the directory structure to routes, but that's just a mapping rather than actually exposing the directories on the server. You can have /src/agents accessible as /agents. Or you could have /alice/bob/agents accessible through /agents. It's all just build tooling and web server config at the end of the day.
That's my point. Having your code in `/src` doesn't mean some of that code doesn't still have routing at `example.com/agents`. It doesn't have to be a real directory.
A `.agents` directory (or routing pretending to be one) is nice because you are fairly unlikely to ever have user-facing `example.com/.agents` as a URL.
Or accept the fact that we're in 2025 and not follow Unix conventions from when paper and printer ink were expensive and they were printing out listings, and just name the thing "source".
I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, but it's still annoying.
Have you considered that there are other metrics people are optimizing for nowadays? Perhaps typeability, screen real estate, familiarity/convention, etc.? Do you really want /User Files/Bob's Files/Coding Projects/Python Projects/Bob's Cool Python Library/Source Code/Model Files/SomeObject.py?
Path length is still a thing in MS Windows, so be careful ;)
Depends on the WinAPI used... I still use C:/src instead of C:/Users/MyUser/src for that reason when working in windows all the same though. Too many unixy utils don't leverage the apis with the longer path, not to mention not supporting the internal certificate store and proxy config.
While we're at this, let's make it rich text please. I want the important filenames to be in bold italic Comic Sans MS.
1. Yes, I have, if you re-read my comment.
2. I don't want to fight extreme positions which I did not make. Read this:
https://gobolinux.org/at_a_glance.html
I didn't say paths have to have spaces, etc. Just be reasonable and <<use full words in the year of our lord 2025>>.
Anything with a capital letter requires hitting two keys: Shift and then the desired letter. Thus /Programs requires 10 keystrokes rather than 9. Even worse, since the capital letter is at the beginning of the directory name, I have to type it and am unable to rely on tab-completion.
/Programs with its ten keystrokes is over twice the keystrokes of /bin and its four. Short names are quicker to type and require less effort. Given that to a first approximation I spend my entire life typing on a keyboard, I very much wish to optimise that experience.
That's really more the fault of the tab completion. There's no reason why it couldn't complete `prog` to `Programs`. It's just Unix tradition that they don't. I would prefer if they did.