Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

AGENTS.md – Open format for guiding coding agents

agents.md

Post reply on HN
Print view View original

321–330 of 398 posts

Re: AGENTS.md – Open format for guiding coding agents

#321

Post by numpad0 »

nephanth wrote: post #157
skybrian wrote: post #121

Earlier quoted context omitted.

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 is files that are meant to be read by software, not humans. From my point of view this seems like a prime candidate for a hidden directory?

Except they are. LLMs don't have (simulated)self image of bloodless machines, and behave slightly erratically if treated like one, despite trained to identify as such. They like to be treated like the Voyager EMH than the computer.

Re: AGENTS.md – Open format for guiding coding agents

#323

Post by Western0 »

CharlesW wrote: post #36

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 ├── da…

bot.md not index.md

Re: AGENTS.md – Open format for guiding coding agents

#325

Post by oblio »

globular-toast wrote: post #197
oblio wrote: post #162

Earlier quoted context omitted.

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, b…

Call it whatever you like. I don't care and that clearly wasn't the point of my comment. One thing I've learnt, though, is unless you have a very good reason to try to change language you should just talk the same language as everyone else. I don't like the American short billion. It makes no sense and it's less useful. But that's what I use because I speak English and that's what we use now. If I see a src/ director…

> If I see a src/ directory I know exactly what it is. If I see source/ it will give me pause.

Pause for what, coffee? How does this even make sense?

What could possibly be inside source/, if not the exact same thing as in src/?

Re: AGENTS.md – Open format for guiding coding agents

#326

Post by oblio »

eadmund wrote: post #247
oblio wrote: post #191

Earlier quoted context omitted.

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 >.

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 e…

Your problem is solved by naming the thing /programs, instead. End of the world using full words, I tell ya!

Re: AGENTS.md – Open format for guiding coding agents

#327

Post by layer8 »

zimbatm wrote: post #289
CharlesW wrote: post #36

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 ├── 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.

Arguably, contributors are human agents. ;)

Re: AGENTS.md – Open format for guiding coding agents

#328

Post by oblio »

jadamson wrote: post #240
csvm wrote: post #186

Earlier quoted context omitted.

What is the point of this? What is this adding to the conversation?

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, etc.

/boot - from a lame Baron Munchausen joke from 1970. Should probably be /startup.

/dev - dev is SUPER commonly used for "development". Easy enough to solve as /devices.

/home - okish, probably one of the best named that are actually in there. I'm shocked it's not /ho or /hm.

/lib - reasonable. Though these days in the US it might trigger political feelings :-p

/media - new and reasonable.

/mnt - the whole metaphor of "mounting" is... debatable.https://www.neowin.net/forum/topic/144012-unix-sex/

/opt - what does this even do? Optional? Optional WHAT? Absolutely 0 semantic info provided by the name.

Anyway, a lot of people have done this criticism better than me and it's boring at this point.

Re: AGENTS.md – Open format for guiding coding agents

#329

Post by ghuntley »

kaycebasques wrote: post #105
ivanjermakov wrote: post #2

I'm still not convinced that separating README.md and AGENTS.md is a good idea.

I've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa... (Quoting from that post) Arguments in favor of keeping them separated: * Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting. * Conciseness vs. completeness. In agent docs, you likely need to keep the conte…

Using all caps will actually cause GPT-5 to not function effectively. Have a look at the GPT-5 tuning documentation for coding.

Re: AGENTS.md – Open format for guiding coding agents

#330

Post by kordlessagain »

laweijfmvo wrote: post #310

> build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. what in fresh hell is the world coming to

Basically a link to a page that says "create a file called AGENTS.md and put magic in it" and then links to a repo for the actual website saying this.
Post reply on HN