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

121–130 of 398 posts

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

#121

Post by skybrian »

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…

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?

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

#122

Post by numpy-thagoras »

p1necone wrote: post #110
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…

I've been trying to keep my baked in llm instructions to a terse ~100 line file, mostly headered sections with 5 or so bullet points each. Covering basic expectations for architecture, test mocking, approach to large changes etc. I can see why for some projects that wouldn't be enough but I feel like it covers everything for most of mine.

Would you be open to sharing this here?

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

#123

Post by iknowstuff »

goosejuice wrote: post #62
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…

I suspect machine readable practices will become standard as AI is incorporated more into society. A good example is autonomous driving and local laws / context. "No turn on red. School days 7am-9am". So you need: where am I, when are school days for this specific school, and what datetime it is. You could attempt to gather that through search. Though more realistically I think the municipality will make the laws req…

Those particular signs are just stupid. The street should be redesigned with traffic calming, narrowing and chicanes so that speeding is not possible.

Slapping on a sign is ineffective

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

#124

Post by time0ut »

tptacek wrote: post #19
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…

It's not just understanding the codebase, it's also stylistic things, like "use this assert library to write tests", or "never write comments", or "use structured logging". It's just as useful --- more so even --- on fresh projects without much code.

Honestly, everything I have written in markdown files as AI context fodder is stuff that I write down for human contributors anyway. Or at least stuff I want to always write down, but maybe only halfway do. The difference now is it is actually being read, seemingly understood, and often followed!

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

#125

Post by stingraycharles »

goosejuice wrote: post #64
throwup238 wrote: post #53

Earlier quoted context omitted.

They are relevant but dumping it all into one document in the project root isn’t as optimal for humans as it is for agents, especially since a lot of that information is irrelevant to someone landing on your repo, who probably just wants to add it to their dependency manifest or install the app followed by usage instructions geared to humans.

Agents are capable of semantic search and reading an entire directory devoted to human readable docs. So I'm not sure this is a particularly good argument. Just make it clear where to find what.

Because managing an AI’s context is important and you don’t want to put stuff in there that’s not relevant.

Just because they can read it and understand it doesn’t mean there are no better alternatives.

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

#127

Post by edoceo »

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

And is also used in my $HOME directory - I like repeating good patterns, or at least well known patterns. (I still have ./etc and ./lib directories in my projects)

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

#128

Post by furyofantares »

stingraycharles wrote: post #7
ivanjermakov wrote: post #2

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

It is. README is for humans, AGENTS / etc is for LLMs. Document how to use and install your tool in the readme. Document how to compile, test, architecture decisions, coding standards, repository structure etc in the agents doc.

There's a lot of shit in my claude.md that would be condescending to a human. Some of it I don't even mean, it's just there to correct egregious patterns the model loves to do. I'm not gonna write "never write fallback code" in my readme, but it saves a lot of time to prevent claude from constantly writing code that would silently fail if it got past me because it contains a fallback path with hardcoded fake data.

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

#130

Post by animal_spirits »

skybrian wrote: post #121
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…

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's so it doesn't clash with any project that actually has a functional `agents/` directory
Post reply on HN