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

11–20 of 48 posts

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

#11

Post by avereveard »

readitalready wrote: post #8
themafia wrote: post #5

The models are so terrible you have to think ahead of them so they don't make mistakes. This is not an upgrade. This is coping behavior.

That's like saying "the programmers are so terrible you have to think ahead of them so they don't make mistakes".

eh, good programmer are goal oriented, today SOTA models still need for the most part step by step guidance, so there's a gap still.

the AGENTS.md pieces that pin specific tool-call shapes or force chain-of-thought before action are coping that ages out, same lifecycle as the retry-with-different-prompt loops or chains of thought prompt most stacks shipped in 2024 to compensate for brittle instruction-following.

not quite there yet, but it's nice to see them being shorter and shorter as model release until all the basic are peeled out by the march of progress and one day only the invariants will be left there

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

#12

Post by httpdemon »

themafia wrote: post #5

The models are so terrible you have to think ahead of them so they don't make mistakes. This is not an upgrade. This is coping behavior.

This is like saying programmers are so terrible that you have to think ahead of them and document your code/project so devs don’t make mistakes and anyone who thinks README files are a good thing are coping.

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

#13

Post by lelandbatey »

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.

The 100% read rate is very harness/CLI dependent. The "original" idea for AGENTS.md was: the AGENTS.md file will be included as-is in the system prompt by the harness, so the agent doesn't have any choice in whether it'll be read or not. For example, this is a shortened form of what opencode sends as a system prompt for a new session when interacting with a provider (displayed in YAML for formatting, and edited for formatting):

    model: foo-model
    max_tokens: 32000
    top_p: 1
    messages:
      - role: system
        content: |
          You are opencode, an interactive CLI tool that helps users with software engineering tasks.
          Use the instructions below and the tools available to you
          # ... snip ...
          Here is some useful information about the environment you are running in:
          
            Working directory: /home/user/dir
            Workspace root folder: /
            Is directory a git repo: no
            Platform: linux
            Today's date: Tue Apr 28 2026
          
          Skills provide specialized instructions and workflows for specific tasks.
          Use the skill tool to load a skill when a task matches its description.
          No skills are currently available.
          Instructions from: /home/user/dir/AGENTS.md
          # Overview
          This directory holds the entirety of the code for the  company. All code lives in Github
          under the `` organization, and beneath that Organization is a wide-and-flat set of all
          the Git repositories of all source code at . That Github repo structure is replicated in
          this directory via `ghorg`.
My AGENTS.md file contents start at the "# Overview" line.

Notice that the harness is just unceremoniously dumping the AGENTS.md file into the exact same text stream as the system prompt, barely contextualizing that hey, starting now, this text is from AGENTS.md and not from the harness.

If you want AGENTS.md to work (likewise, if you want skills or anything else to work) you have to know how the harness is handling/feeding them to the LLM, because no LLM will reliably look on their own.

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

#14

Post by chickensong »

weiliddat wrote: post #7

I suspect the harness (of which AGENTS and skills and similar things) should be abstracted for better overall performance. This article doesn't really go into detail about model preferences, but some other benchmarks show that different models have differnt preferences of how to use certain tools (probably related to their post training material), and it should really be managed invisibly to me as the end user. Also…

Claude self-reflects and updates based on feedback pretty well these days, but seems to lean on memory more than updating CLAUDE.md. I don't know how well it adheres to memory, but it seems to work sometimes. I don't like how the memory is stored outside of the project directory though.

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

#15

Post by weiliddat »

chickensong wrote: post #14
weiliddat wrote: post #7

I suspect the harness (of which AGENTS and skills and similar things) should be abstracted for better overall performance. This article doesn't really go into detail about model preferences, but some other benchmarks show that different models have differnt preferences of how to use certain tools (probably related to their post training material), and it should really be managed invisibly to me as the end user. Also…

Claude self-reflects and updates based on feedback pretty well these days, but seems to lean on memory more than updating CLAUDE.md. I don't know how well it adheres to memory, but it seems to work sometimes. I don't like how the memory is stored outside of the project directory though.

Hmm I would hope that's for better quality (if there's somehow model-specific optimizations) or search/retrieval methods down the line. But can't help but feel like the labs/providers might try to lock-in customers by making things non-portable/opaque.

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

#16

Post by acgourley »

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…

Everytime I've asked a model to write it's Agents/Claude file it's been pretty bad actually, are you sure writing these files is actually in distribution right now?

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

#17

Post by stavros »

weiliddat wrote: post #6
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.

This is more a harness thing signaling the presence or forcing a read on AGENTS/CLAUDE.md right?

Yes it is, the main feature that differentiates AGENTS.md from other files is that the former is usually loaded into the context automatically.

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

#18

Post by chickensong »

weiliddat wrote: post #15
chickensong wrote: post #14

Earlier quoted context omitted.

Claude self-reflects and updates based on feedback pretty well these days, but seems to lean on memory more than updating CLAUDE.md. I don't know how well it adheres to memory, but it seems to work sometimes. I don't like how the memory is stored outside of the project directory though.

Hmm I would hope that's for better quality (if there's somehow model-specific optimizations) or search/retrieval methods down the line. But can't help but feel like the labs/providers might try to lock-in customers by making things non-portable/opaque.

Oh yeah, it definitely feels like a scramble to add lock-in features.

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

#19

Post by weiliddat »

Rekindle8090 wrote: post #9
readitalready wrote: post #8

Earlier quoted context omitted.

That's like saying "the programmers are so terrible you have to think ahead of them so they don't make mistakes".

No it's not actually anything like that whatsoever. Programmers are objectively, infinitely more capable than llms. Stop anthropomorphizing algorithms.

I would be very curious which programmers you have in mind when comparing to llms. Like the median programmer, or like the top 10%.

I feel like we've passed the point where an average-effort Claude Code / Cursor / Codex initialized (like basic docs, skills) project would produce a better product (not just code) than if you hired a median programmer to work on that project.

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

#20

Post by readitalready »

Rekindle8090 wrote: post #9
readitalready wrote: post #8

Earlier quoted context omitted.

That's like saying "the programmers are so terrible you have to think ahead of them so they don't make mistakes".

No it's not actually anything like that whatsoever. Programmers are objectively, infinitely more capable than llms. Stop anthropomorphizing algorithms.

lol no. LLMs are infinitely more capable than programmers.

People really do think too highly of themselves.

Post reply on HN