Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

augmentcode.com

Post reply on HN
Print view View original

21–30 of 48 posts

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#21

Post by bushido »

I think the main thing which a lot of these articles miss is it's not just your Agents.md which can give you a model upgrade or the inverse.

But everything your harness looks at could be this. So the skills in your code base, the commands that you've added, the memories that were auto created, they all work towards improving or completely destroying your productivity.

And most of it is hidden. You hear people talk about this all the time where they'll be like, Oh, I use GSD or I use Superpowers and my results have gotten worse.

Your results might have gotten worse precisely because you use them (along with your memories and other skills).

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#22

Post by simonw »

Most of my projects are without an AGENTS.md/CLAUDE.md at the moment. I've found that if the project itself is in good shape - clear docs, comprehensive tests - you don't need to tell the coding agent much in order for it to be productive.

I start a whole lot of my sessions with "Run tests with 'uv run pytest'" and once they've done that they get the idea that they should write tests in a style that fits the existing ones.

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#23

Post by kajman »

chickensong wrote: post #10

It's cool that they did some measurements, but unfortunately there's not much to learn from the article unless you're using really outdated files that you wrote by hand. The agent should know how to write a good file. For existing files, the agent will carry on a bad structure unless you specifically ask it to refactor and think about what's actually helpful. In general, it should be a lean file that tells the agent…

I don't have a ton of experience with this, but every attempt I've made to quickly get an LLM to one-shot an AGENTS file has been too verbose in all the wrong areas. I'm not convinced LLMs are actually good at summarizing anything complex. Maybe some "blessed" prompts will bubble up in time that change my mind.

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#24

Post by asdfasgasdgasdg »

simonw wrote: post #22

Most of my projects are without an AGENTS.md/CLAUDE.md at the moment. I've found that if the project itself is in good shape - clear docs, comprehensive tests - you don't need to tell the coding agent much in order for it to be productive. I start a whole lot of my sessions with "Run tests with 'uv run pytest'" and once they've done that they get the idea that they should write tests in a style that fits the existing…

Wouldn't the AGENTS.md containing the line, "When you make changes, they should be tested. Run tests with `uv run pytest`" basically have the same effect and save you some typing? I've never used AGENTS.md myself but I'd like to look into it because I find my agent rediscovering using a bunch of file reads very frequently in my current project.

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#25

Post by Neywiny »

rgbrgb wrote: post #2

I'd guess the same has always been true for READMEs / human dev docs. Of course it doesn't transfer directly but still feels incredible to be in an age where we can measure such (previously) theoretical things with synthetic programmers.

Yeah isn't this is obvious? Bad docs create triple work: you do it wrong (1) you figure out it's not working because the doc is wrong (2) you do it the right way (3). Between 2 and 3 is figuring out what the right way is, which a good doc ideally shortcuts.

But obviously if you tell somebody "make a boiled egg. To boil an egg you have to crack it into the pan first." That's a lot worse than "make a boiled egg." Especially when you have an infinitely trusting, 0 common sense executor like an agentic model.

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#27

Post by qingcharles »

simonw wrote: post #22

Most of my projects are without an AGENTS.md/CLAUDE.md at the moment. I've found that if the project itself is in good shape - clear docs, comprehensive tests - you don't need to tell the coding agent much in order for it to be productive. I start a whole lot of my sessions with "Run tests with 'uv run pytest'" and once they've done that they get the idea that they should write tests in a style that fits the existing…

That's wild. I couldn't live without my AGENTS to make sure it keeps to the coding styles I prefer. Especially needed on greenfield projects.

A lot of my projects are built with platform versions from the last 12 months which had zero or very small amounts in the core training for the LLM, so they'll tend to avoid using the latest language options unless you prescribe them in AGENTS.

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#28

Post by qingcharles »

forgotusername6 wrote: post #3

Interesting that they had a 100% read rate of agents.md. In my test repo lower down agents.md files were occasionally missed by vscode copilot. That fact put me off putting too much effort into nesting agents.md files too much within the repo and I've been focusing on agent skills instead.

I often start a new session with tagging AGENTS.md in the prompt just to make sure because I've had the same issue happen a couple of times.

Re: A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all

#30

Post by simonw »

asdfasgasdgasdg wrote: post #24
simonw wrote: post #22

Most of my projects are without an AGENTS.md/CLAUDE.md at the moment. I've found that if the project itself is in good shape - clear docs, comprehensive tests - you don't need to tell the coding agent much in order for it to be productive. I start a whole lot of my sessions with "Run tests with 'uv run pytest'" and once they've done that they get the idea that they should write tests in a style that fits the existing…

Wouldn't the AGENTS.md containing the line, "When you make changes, they should be tested. Run tests with `uv run pytest`" basically have the same effect and save you some typing? I've never used AGENTS.md myself but I'd like to look into it because I find my agent rediscovering using a bunch of file reads very frequently in my current project.

It would, but then I'd have to copy that file into 100+ repos.

I don't want it in a single global config because I like to stay with the defaults to avoid confusing myself, especially when I'm writing about how coding agents work for other people.

Post reply on HN