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

91–100 of 398 posts

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

#91

Post by mvkel »

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…

This is mostly true if the existing codebase is largely self documented, which is rare

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

#93

Post by chrismorgan »

ethan_smith wrote: post #10
eats_indigo wrote: post #3

In what way is this a format or standard? It's just markdown in a namespce

Standards derive their value precisely from being simple and widely adopted - think of .gitignore, CONTRIBUTING.md, or LICENSE files that work because everyone agrees on their location and purpose.

.gitignore is not a standard: it’s a format used by one tool. A few other tools piggy-back on it (e.g. ripgrep ignores paths matching in .gitignore, .hgignore, &c. by default), not infrequently to confusion.

CONTRIBUTING.md is not a standard: it’s a convention pushed by one platform, used by some projects (but many more will not write down such information, or put it in a README file, or put it in some other documentation).

LICENSE is definitely not a standard: it’s one of a wide variety of names people use to hold licensing information, which some tools will be able to detect. I just looked through my /usr/share/licenses, of 1135 files, only 300 are named LICENSE—it’s the most popular single name, sure, with COPYING next at 182, but it’s still definitely a minority, though in certain ecosystems it may be more popular. Any license-detection tooling will be scanning for a lot more file names. “LICENSE” is a very weak convention, compared with the others.

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

#94

Post by echelon »

riffic wrote: post #70
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…

.well-known/

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_Base_Directory

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

#95

Post by chrismorgan »

sergiotapia wrote: post #8

New Phoenix Framework projects have an AGENTS.md file in the root! It's really cool. https://x.com/alkadaemon/status/1955348410145358199

https://github.com/phoenixframework/phoenix/blob/main/instal...

That’s insane. 3000 words of prose boilerplate about the language and framework. Sounds like you need, at the very least, some sort of import directive. I have no idea if “Read and follow the instructions in path/to/phoenixframework/AGENTS.md.” would work.

And then the eclectic mixture of instructions with a variety of ways of trying to bully an intransigent LLM into ignoring its Phoenix-deficient training… ugh.

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

#96

Post by cma »

arrowsmith wrote: post #22
eats_indigo wrote: post #3

In what way is this a format or standard? It's just markdown in a namespce

All the different coding agents put their "rules" in different places: .cursor, CLAUDE.md etc.. It makes no sense and it really needs standardisation. I hope this catches on.

As a workaround you can add a wrapper launcher script that symlinks them and then removes the symlink after you exit

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

#98

Post by _mu »

tomComb wrote: post #73
_mu wrote: post #14

Make sure to check out https://agent-rules.org/ as well for more background on this initiative. More and more tools are adopting the standard. Amp used to have an "RFC 9999" article on their website for this as well but the link now appears to be broken. You can symlink your Cursor / Windsurf / whatever rules to AGENTS.md for backwards compatibility.

Ok, I looked at your agent-rules and it sounds good except for a couple things ... "Guidance for Use" Your preference for bullet lists over headers is odd. This comes down to what works best with the models - they are interpreting it. This is a moving target. If you believe that your suggestion works best you should provide some sort of evidence. The default would be to not even get into that sort of thing. Non-Hiera…

I did not write agent-rules, I'm just linking to it.

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

#100

Post by [deleted] »

naniwaduni wrote: post #56
ameliaquining wrote: post #45

Earlier quoted context omitted.

If there were already a universal convention on where to put that stuff, then probably the agents would have just looked there. But there's not, so it was necessary to invent one.

Reality is just that people neglected onboarding docs until LLM-based coding agents put them in a position to directly benefit from having more knowledge of the codebase explicitly written down.

[deleted]
Post reply on HN