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

261–270 of 398 posts

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

#261

Post by criley2 »

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…

Better to work with the tools we have instead of the tools we might one day have. If you want agents to work well today, you need to build for the agents we have today.

We may never achieve your future where context is unlimited, models are trained on your codebase specifically, and tokens are cheap enough to use all of this. We might have a bubble pop and in a few years we could all be paying 5-10X current prices (read: the actual cost) for similar functionality to today. In that reality, how many years of inferior agent behavior do you tolerate before you give up hoping that it will evolve past needing the tweaks?

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

#262

Post by criley2 »

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…

Your prompt is pretty basic. Both Claude Code and Github Copilot having similar features. Claude Code has `init` which has a lot of special sauce in the prompt to improve the CLAUDE.md. And github copilot added a self-documenting prompt as well that runs on new repos, and you can see their prompt here https://docs.github.com/en/copilot/how-tos/configure-custom-...

Reading their prompt gives ideas on how you can improve yours.

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

#263

Post by varispeed »

When did this happen - first corporates where wary of using AI generated code due to copyright concerns and now we have full embrace?

I guess we are not yet in the phase where everyone will be scrambling to find competent engineers to clean-up the AI mess in their codebases?

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

#267

Post by clbrmbr »

time0ut wrote: post #124
tptacek wrote: post #19

Earlier quoted context omitted.

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!

So true. I find myself doing a lot more documentation these days as it is actually having a direct visible benefit. There’s a bit of a mirage here, but hey it’s getting me to document so shhh.

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

#268

Post by fallpeak »

thrown-0825 wrote: post #251
fallpeak wrote: post #232

Earlier quoted context omitted.

In my opinion an AGENTS.md file isn't an artifact at all (in the sense of being a checked-in part of the codebase), it's part of the prompt. You should gitignore them and use them to give the LLM a brief overview of the things that matter to your work and the requests you are making.

every example in the wild has these checked in and treated like a lock file where everyone is scared to touch it and introduce weird behavior. personally i think this pattern is a dead end and trying to build deterministic agentic behavior on top of inherently non-deterministic systems is a fools errand.

I mean, by construction you're only ever going to see the examples where people checked them in and published that. It doesn't mean that other people aren't getting more use out of local instructions customized to their particular work.

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

#269

Post by jppittma »

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?

Because you're not an (llm) agent and they're not for your consumption? You probably don't need the context in those docs.

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

#270

Post by bgwalter »

varispeed wrote: post #263

When did this happen - first corporates where wary of using AI generated code due to copyright concerns and now we have full embrace? I guess we are not yet in the phase where everyone will be scrambling to find competent engineers to clean-up the AI mess in their codebases?

It is only the "AI" companies that force their employees to babysit LLMs, so very few real projects do this in the wild.
Post reply on HN