4 ms·

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

diggan 1y ago
At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.
- andyferris 1y ago
  For ages, many projects have README.md for marketing/landing page (i.e. users) and CONTRIBUTING.md for developers. Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.
  - mrklol 1y ago
    I feel like as a human you should still do it like you said. But in the current state it’s advantageous to give the LLM proper instructions which are distinct to human instructions. LLMs aren’t drop in replacements for developers … yet (or never).
stingraycharles 1y ago
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.
- darepublic 1y ago
  Compile, test, architecture would be very welcome in the readme too Id wager
  - silversmith 1y ago
    Where contributors are the audience, yes. For things like libraries, I care about those things only if I run into a bug, and have enough resources to attempt a fix.
    - darepublic 1y ago
      It can help even when using the library and not contributing. It helps you to use the api better imo, because usually the abstraction is not perfect and having even a general sense of how the sausage is made will prevent you from falling victim to gotchas. But then on the downside it lowers the mystique of the library. Some coders prefer to be magicians.
- sponnath 1y ago
  Why would these things not be relevant for humans?
  - throwup238 1y ago
    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.
    - goosejuice 1y ago
      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.
      - stingraycharles 1y ago
        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.
        goosejuice 1y ago
        That's also not a strong argument? Agents often have system prompts specific to their purpose. Having a single dump of agent instructions will increase noise in the context.
- crazylogger 1y ago
  We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?
- furyofantares 1y ago
  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.
blinkymach12 1y ago
I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.
- esafak 1y ago
  My READMEs don't have things like "don't run the whole test suite unless I instruct you to because it will take too long; run targeted tests instead".
  - viraptor 1y ago
    Why not? "For most development we recommend running single/specific tests since the whole suite is slow/expensive." sounds like a great thing to put in the readme.
  - ecb_penguin 1y ago
    That seems exactly like something you would want to tell another developer
- sothatsit 1y ago
  You're going to include specific coding style rules in your README? Or other really agent-specific things like guidance about spawning sub-agents? They are separate for a good reason. My CLAUDE.md and README.md look very different.
  - bongodongobob 1y ago
    Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
    - CuriouslyC 1y ago
      To share the most effective workflows so people don't have to muddle around figuring out what to do?
petesergeant 1y ago
Perhaps. I let Claude put whatever it wants in its Claude file and check it’s not batshit from time to time, where I’m very protective of the high-quality README I write for humans. The Claude file has stuff that would be obvious to a human and weird to jam into the README (we use .spec.ts not .test.ts) but that Claude needs in order to get things right.
trailrunner46 1y ago
One reason to consider is around context usage with LLMs. Less is generally better and README.md files are often too much text some of which I don’t want in every context window. I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.
kaycebasques 1y ago
I've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separated https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa... (Quoting from that post) Arguments in favor of keeping them separated: * Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting. * Conciseness vs. completeness. In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality. In internal eng docs, we ideally aim for 100% completeness. I.e. every important design decision, API reference, workflow, etc. is documented somewhere. * Differing knowledge needs. The information that LLMs need help with is not the same as the information that human engineers need help with. For example, Gemini 2.5 Pro has pretty good built-in awareness of Pigweed’s C++ Style Guide. I tested that assertion by invoking the Gemini API and instructing it Recite the Pigweed C++ Guide in its entirety. It did not recite in full, but it gave a detailed summary of all the points. So the Gemini 2.5 Pro API was either trained on the style guide, or it’s able to retrieve the style guide when needed. Therefore, it’s not necessary to include the full style guide as AGENTS.md context. (Credit to Keir Mierle for this idea.) Arguments against: * Duplication. Conceptually, agent docs are a subset of internal eng docs. The underlying goal is the same. You’re documenting workflows and knowledge that’s important to the team. But now you need to maintain that same information in two different doc sets.
- CGamesPlay 1y ago
  > Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting. To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean there are consequences to doing suchandsuch, like being fired or causing production downtime. So the same message will be received differently by the different types of readers.
  - skhameneh 1y ago
lmeyerov 1y ago
We find it useful: * Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a < 500loc ai/readme.md with must haves, links to others, and meta how-to-use * Similar to IaaC, useful to separate out as not really ready the same way we read it, and many markdowns are really scripts written in natural language, eg, plan.md.template
rogeliodh 1y ago
Some time ago a lot of projects had a README and a BUILD/README.build/DEVELOPMENT file... I think AGENTS.md is more akin to this last file.

At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.

andyferris 1y ago
For ages, many projects have README.md for marketing/landing page (i.e. users) and CONTRIBUTING.md for developers. Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.
- mrklol 1y ago
  I feel like as a human you should still do it like you said. But in the current state it’s advantageous to give the LLM proper instructions which are distinct to human instructions. LLMs aren’t drop in replacements for developers … yet (or never).

stingraycharles 1y ago

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.

darepublic 1y ago
Compile, test, architecture would be very welcome in the readme too Id wager
- silversmith 1y ago
  Where contributors are the audience, yes. For things like libraries, I care about those things only if I run into a bug, and have enough resources to attempt a fix.
  - darepublic 1y ago
    It can help even when using the library and not contributing. It helps you to use the api better imo, because usually the abstraction is not perfect and having even a general sense of how the sausage is made will prevent you from falling victim to gotchas. But then on the downside it lowers the mystique of the library. Some coders prefer to be magicians.
sponnath 1y ago
Why would these things not be relevant for humans?
- throwup238 1y ago
  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.
  - goosejuice 1y ago
    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.
    - stingraycharles 1y ago
      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.
      - goosejuice 1y ago
        That's also not a strong argument? Agents often have system prompts specific to their purpose. Having a single dump of agent instructions will increase noise in the context.
crazylogger 1y ago
We have CONTRIBUTING.md for that. Seems to me the author just doesn't know about it?
furyofantares 1y ago
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.

blinkymach12 1y ago

I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.

esafak 1y ago
My READMEs don't have things like "don't run the whole test suite unless I instruct you to because it will take too long; run targeted tests instead".
- viraptor 1y ago
  Why not? "For most development we recommend running single/specific tests since the whole suite is slow/expensive." sounds like a great thing to put in the readme.
- ecb_penguin 1y ago
  That seems exactly like something you would want to tell another developer
sothatsit 1y ago
You're going to include specific coding style rules in your README? Or other really agent-specific things like guidance about spawning sub-agents? They are separate for a good reason. My CLAUDE.md and README.md look very different.
- bongodongobob 1y ago
  Why would you publish agent specific things to your codebase? That's personal preference and doesn't have anything to do with the project.
  - CuriouslyC 1y ago
    To share the most effective workflows so people don't have to muddle around figuring out what to do?

petesergeant 1y ago

Perhaps. I let Claude put whatever it wants in its Claude file and check it’s not batshit from time to time, where I’m very protective of the high-quality README I write for humans. The Claude file has stuff that would be obvious to a human and weird to jam into the README (we use .spec.ts not .test.ts) but that Claude needs in order to get things right.

trailrunner46 1y ago

One reason to consider is around context usage with LLMs. Less is generally better and README.md files are often too much text some of which I don’t want in every context window. I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.

kaycebasques 1y ago

I've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separated https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa... (Quoting from that post) Arguments in favor of keeping them separated: * Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting. * Conciseness vs. completeness. In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality. In internal eng docs, we ideally aim for 100% completeness. I.e. every important design decision, API reference, workflow, etc. is documented somewhere. * Differing knowledge needs. The information that LLMs need help with is not the same as the information that human engineers need help with. For example, Gemini 2.5 Pro has pretty good built-in awareness of Pigweed’s C++ Style Guide. I tested that assertion by invoking the Gemini API and instructing it Recite the Pigweed C++ Guide in its entirety. It did not recite in full, but it gave a detailed summary of all the points. So the Gemini 2.5 Pro API was either trained on the style guide, or it’s able to retrieve the style guide when needed. Therefore, it’s not necessary to include the full style guide as AGENTS.md context. (Credit to Keir Mierle for this idea.) Arguments against: * Duplication. Conceptually, agent docs are a subset of internal eng docs. The underlying goal is the same. You’re documenting workflows and knowledge that’s important to the team. But now you need to maintain that same information in two different doc sets.

CGamesPlay 1y ago
> Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting. To pile on to this, an agent needs to see "ABSOLUTELY NEVER do suchandsuch" to not do suchandsuch, but still has a pretty fair chance of doing it by accident. A talented human seeing "ABSOLUTELY NEVER do suchandsuch" will interpret this to mean there are consequences to doing suchandsuch, like being fired or causing production downtime. So the same message will be received differently by the different types of readers.
- skhameneh 1y ago

lmeyerov 1y ago

We find it useful: * Agents still kinda suck so need the help around context management and avoiding foot guns. Eg, we make a < 500loc ai/readme.md with must haves, links to others, and meta how-to-use * Similar to IaaC, useful to separate out as not really ready the same way we read it, and many markdowns are really scripts written in natural language, eg, plan.md.template

rogeliodh 1y ago

Some time ago a lot of projects had a README and a BUILD/README.build/DEVELOPMENT file... I think AGENTS.md is more akin to this last file.