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

131–140 of 398 posts

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

#131

Post by wfhrto »

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.

The difference now is that people are actively trying to remove people (others and themselves) from software development work, so the robots have to have adequate instructions. The motivation is bigger. To dismantle all human involvement with software development is something that everyone wants, and they want it yesterday.

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

#133

Post by CGamesPlay »

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…

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

To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean there are consequences to doing suchandsuch, like being fired or causing production downtime. So the same message will be received differently by the different types of readers.

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

#134

Post by binarysneaker »

vinnymac wrote: post #106
echelon wrote: post #94

Earlier quoted context omitted.

This. Projects need to stop inventing their own root level files and directories. Stop polluting the root dir. I'm not a fan of the name "well-known", but at least it's a convention [1]. I think it'd be great if we took something like XDG [2] and made it common for repositories, build scripts, package managers, tooling configs, etc. [1] https://www.rfc-editor.org/rfc/rfc8615 [2] https://wiki.archlinux.org/title/XDG_B…

.config is a good name, and has a small following https://dot-config.github.io

Reminds me of https://xkcd.com/927/

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

#135

Post by theletterf »

blinkymach12 wrote: post #13

We'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…

Yes! That was precisely my point here: https://news.ycombinator.com/item?id=44837875

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

#136

Post by samename »

wfhrto wrote: post #131
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.

The difference now is that people are actively trying to remove people (others and themselves) from software development work, so the robots have to have adequate instructions. The motivation is bigger. To dismantle all human involvement with software development is something that everyone wants, and they want it yesterday.

everyone? source?

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

#137

Post by meander_water »

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…

There shouldn't be anything stopping you from doing that.

You can just use the AGENTS.md file as an index pointing to other doc files.

This example does that -

https://github.com/apache/airflow/blob/main/AGENTS.md

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

#138

Post by skhameneh »

CGamesPlay wrote: post #133
kaycebasques wrote: post #105

Earlier quoted context omitted.

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…

> 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. To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean…

Negative assertions can lead to unwanted weights in the context.

I've found positive assertions to be more predictable.

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

#140

Post by setopt »

meander_water wrote: post #137
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…

There shouldn't be anything stopping you from doing that. You can just use the AGENTS.md file as an index pointing to other doc files. This example does that - https://github.com/apache/airflow/blob/main/AGENTS.md

The point is that .agents is a hidden file while AGENTS.md is in your face like a README intended for humans.

Having an in-your-face file that links to a hidden file serves no purpose.

Post reply on HN