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

221–230 of 398 posts

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

#221

Post by whywhywhywhy »

nivertech wrote: post #202
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 looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself. AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support…

>whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste

Not sure it is when you consider how agents deal with large files, hows it gonna follow coding conventions if it doesn’t even grep them or just read the first few lines

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

#222

Post by Philpax »

vFunct wrote: post #40
CuriouslyC wrote: post #37

Earlier quoted context omitted.

Have you taken a Waymo?

The limited self-driving cars, with a remote human operator? no, I never have.

This rather underplays the experience of riding a Waymo. Where it works, it works: you get in and it takes you to the place, no human intervention required at any point.

By analogy, the first hands-off coding agents may be like that: they may not work for everything, but where they do, they could work without human intervention.

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

#223

Post by irthomasthomas »

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 is what I do. Everywhere my agent works it uses a .agent dir to store its logs and intermediary files. This way the main directories aren't polluted with cruft all the time.

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

#224

Post by athrowaway3z »

jillesvangurp wrote: post #198
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…

Here's a prompt I wrote a few days ago for codex: Analyze the repository and add a suitable agents.md It did a decent job. I didn't really have much to add to that. I guess, having this file is a nice optimization but obviously it doesn't contain anything it wasn't able to figure out by itself. What's really needed is a per repository learning base that gets populated with facts the agents discovers during it's many…

I see the groundhog day problem as a feature, not a bug.

It's an organizational challenge, requiring a top level overview and easy to find sub documentation - and clear directives to use them when the AI starts architecting on a fresh start.

Overall, it's a good sign when a project is understandable in small independent chunks that don't demand a programmer/llm take in more context than was referenced.

I think the sweet spot would be all agents agree on a MUST-READ reference syntax for inside comments & docs that through simple scanning forces the file into the context. eg

// See @{../docs/payment-flow.md} for the overall design.

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

#225

Post by theshrike79 »

_ache_ wrote: post #215
theshrike79 wrote: post #207

Earlier quoted context omitted.

Context is not infinite. Saving context for what matters is key in working with LLMs.

Context is not infinite yet. New standard for something that maybe false very soon is just a bad idea.

We all want to move to local models eventually for privacy and reliability.

They don't (and won't) have infinite context without trickery or massive €€€ use.

The current crop of online LLMs are just running on VC money slightly tapered with subscriptions - but still at a loss. The hype and money will run out, so use them as much as possible now. But also keep your workflows so that they will work locally when the time comes.

Don't be that 10x coder who becomes a 0.1x coder when Anthropic has issues on their side =)

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

#227

Post by mustaphah »

thrown-0825 wrote: post #203

Including artifacts like this which are intended only to be consumed by ai defeats the entire point.

Fair point, but if it's minimal and useful for agents, I'm okay with it.

Humans and AIs have different weak spots: we can infer intent from convention, but an AI often struggles unless you spell it out. Ignoring that gap just to keep things "purely human" feels counterproductive. Agents deserve some sympathy.

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

#228

Post by nivertech »

whywhywhywhy wrote: post #221
nivertech wrote: post #202

Earlier quoted context omitted.

This looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself. AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support…

>whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste Not sure it is when you consider how agents deal with large files, hows it gonna follow coding conventions if it doesn’t even grep them or just read the first few lines

Claude Code globs and greps files, while Sourcegraph Amp uses RAG.

But yes, naive coding agents will fill the context with the entire large file.

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

#229

Post by xmorse »

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…

You can put your docs in folders and reference them in AGENTS.md

Or use urls in your main AGENTS like I do for https://gitchamber.com

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

#230

Post by ghuntley »

brainlessdev wrote: post #194
kristopolous wrote: post #193

Earlier quoted context omitted.

it's actually by sourcegraph and it's been up since may. Here's where it used to go: https://web.archive.org/web/20250702163859/ampcode.com/agent... Here's their announcement https://ampcode.com/news/AGENT.md The openai thing is some recent partnership I'm guessing Interesting enough, Sourcegraph had agent.md which now 301's to agents.md (with the s).

Interestingly, the old one mentioned CLAUDE.md and ln -s, but the new one does not. The whole website is just a marketing/partnerships battle, it seems.

hi, one of the folks behind this. Back in May, @sqs acquired the domain and launched the website above, committing to relocate if the agents.md domain could be acquired. In July, I put out [1] RFC 9999 as a call to the industry that we need to fix this mess. Shortly afterwards OpenAI was able to obtain the domain and thus we (Amp) followed through on the commitment and worked with other vendors to move from AGENT.md to AGENTS.md.

[1] https://web.archive.org/web/20250708160846/https://ampcode.c...

Post reply on HN