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

351–360 of 398 posts

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

#351

Post by verdverm »

theshrike79 wrote: post #205
bryanrasmussen wrote: post #172

Earlier quoted context omitted.

so you would have an Agents.md in your testing folder and it would describe how to run the tests or generate new tests for the project - am I understanding the usage correctly?

Pretty much yes Most systems have a global config, project config and personal config. But I do like the directory style to keep context low. Cursor did it best with actual glob filters in the front matter that tell the LLM "only read this if the file you're processing ends with *.php"

Copilot does globs too, but if you dig into the actual prompt sent out...

They are not doing this mechanically (read file, compare to globs to add more context), they try to rely on the model to notice and do another read. It has been unreliable. I have had better results by adding instructions like...

"If the user asks about X, Read `./path/to/inst.md`"

Still lots of DX to do in this space

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

#352

Post by dingnuts »

oehpr wrote: post #297
zimbatm wrote: post #289

Earlier quoted context omitted.

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.

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

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

#353

Post by dingnuts »

organsnyder wrote: post #313
oehpr wrote: post #297

Earlier quoted context omitted.

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.

[flagged]

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

#355

Post by astrobe_ »

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

You didn't get the memo? Vibe coding, obviously. Joke aside, I remember there was an article here a few weeks ago maybe about writing docs for bots about which commenters here said it was no different that writing better docs.

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

#356

Post by whywhywhywhy »

spawarotti wrote: post #21

At 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 mean the agents are to lazy to read any of this anyway and often will forget the sort of instructions being spam these with after 3 more instructions too.

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

#357

Post by skybrian »

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?

Why not both? Sure, it was written for the LLM, but since it’s in English and meant as a concise summary, you will learn things by reading it.

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

#358

Post by mxmilkiib »

dingnuts wrote: post #353
organsnyder wrote: post #313

Earlier quoted context omitted.

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.

[flagged]

you've not had your "oh shit" moment yet?

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

#359

Post by von_lohengramm »

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

Earlier quoted context omitted.

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/?

While the meaning of "source" may be intuitively obvious, it's still relatively unfamiliar as "src" is far more prevalent than "source" when referring to source files. While "id est" may be equivalent to "i.e.", you'd still naturally pause when reading text using the former instead of the latter, because the latter is far more prevalent in usage than the former.

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

#360

Post by j2kun »

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.

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.
Post reply on HN