Aside from it being "instructions for agents", I'm not sure I understand how this isn't just a markdown file that more or less reads like a readme that targets more junior engineers.
No, you nailed it. The rest is theater.
AGENTS.md – Open format for guiding coding agents
331–340 of 398 posts
Re: AGENTS.md – Open format for guiding coding agents
#332This 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…
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.
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.
Re: AGENTS.md – Open format for guiding coding agents
#333Earlier quoted context omitted.
Well, it wouldn't even be the first time. We've completely redesigned society around cars - making the most human populated environments largely worse for humans along the way. Universal sidewalks (not really needed with slow moving traffic like horses and carts - though nice even back then), traffic lights, stop signs, street crossing, interchanges, etc.
As a cyclist, I’m with you 100%. Unfortunately we’re probably going to do it again with self-driving cars, with segregated lanes, special markers, etc.
A pessimistic look at self driving cars: https://www.youtube.com/watch?v=040ejWnFkj0&t=3148s
If we end up where the video presents, humans don't deserve technology of any kind.
Re: AGENTS.md – Open format for guiding coding agents
#334I like this. I was using README.md, like many folks, which wasn’t bad. The main issue is the agent is typically updating it as well while building out the prototype.
Re: AGENTS.md – Open format for guiding coding agents
#335This 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…
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.
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.
Re: AGENTS.md – Open format for guiding coding agents
#336Earlier quoted context omitted.
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?
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 >.
What's wrong with spaces? Macs support them since 80s. The only problem with spaces is caused by *nix, *nix shells, basically by Linux.
Re: AGENTS.md – Open format for guiding coding agents
#337Earlier quoted context omitted.
we're -> we are I've -> I have & -> and co. -> company won't -> will not it's -> it is
/usr -> Program Files (hello spaces my old friends, you've come to break my apps again) /var -> ProgramData (but no spaces here) /home -> Documents and Settings /etc -> Control Panel
Spaces break things only in Lnux; Mac and Windows support them since beginning. Why should we write without spaces as if we were in 5th century?
Re: AGENTS.md – Open format for guiding coding agents
#338We'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. I think we should focus on our own project documentation being comprehensive (e.g. the contents of this AGENTS.md are appropriate to live somewhere in our documentation), but we should always write for humans. The LLM's whole shtick is that it can read an…
I think they'll always need special guidance for things like business logic. They'll never know exactly what it is that you're building and why, what the end goal of the project is without you telling them. Architectural stuff is also a matter of human preference: if you have it mapped out in your head where things should go and how they should be done, it will be better for you when reading the changes, which will b…
Indeed I have observed that my coworkers "never know exactly what it is that [we]'re building and why, what the end goal of the project is without [me] telling them"
Re: AGENTS.md – Open format for guiding coding agents
#339Why this even required..
It makes people feel like they're in control of the text prediction agent when actually it'll only follow this some of the time.
1. I tell Copilot until I'm blue in the face that the project must build.
2. Copilot assures me it has fixed the build errors it created.
3. Still get build errors
4. Run out of tokens so I come back next month and repeat.
Re: AGENTS.md – Open format for guiding coding agents
#340Earlier quoted context omitted.
What I took out of it is that we are human, and humans use abbreviations to save time and effort, not because printer ink was expensive in the '70s.
The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed - I assume as most first timers do - that the folder is basically the location of miscellaneous files ("et caetera"). Oh, let alone the fact that a bunch of the abbreviations are utterly non-intuitive to first timers. /bin - binaries - nobody born after circa 1980 calls them that anymore. Executables, applications, apps, e…
> The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed
They're completely ambiguous to someone who doesn't speak English.
> /mnt - the whole metaphor of "mounting" is... debatable
What? Have you never heard of mounting a picture on a wall? Mounting an engine? That's the metaphor.
> Anyway, a lot of people have done this criticism better than me and it's boring at this point.
Your original complaint was about "src", suggesting calling it "source", which is still ambiguous by your own standard. Source of what? How is someone going to know what "source" means if they've never heard of booting a computer? Who is the audience for this change?
Some of your suggestions aren't meritless, but your jumping-off point certainly was.