4 ms·

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?
    - bongodongobob 1y ago
      You're going to try to tell people how to code with agents in the readme? Why?
  - ameliaquining 1y ago
    README often contains only basic context for the project and instructions for basic tasks like running it and building it from source. If additional information for developers, like coding conventions, is short enough compared to the rest of the README then it sometimes gets added there too, but if there's a lot of it then it's frequently kept elsewhere to prevent README from getting overwhelming for end users and random people just checking out the project.
    - blinkymach12 1y ago
      I don't think anything requires a README.md to be monolithic. They often provide the introductory material that you mention here, then link out to other appropriate files for contribution guidelines, etc.
  - sothatsit 1y ago
    It should not contain personal preference. It should contain project conventions. Project guidelines, how to build your project, where to find or implement different types of features, are not personal preference. If different members of your team disagree on these things, that is a problem.

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?
  - bongodongobob 1y ago
    You're going to try to tell people how to code with agents in the readme? Why?
- ameliaquining 1y ago
  README often contains only basic context for the project and instructions for basic tasks like running it and building it from source. If additional information for developers, like coding conventions, is short enough compared to the rest of the README then it sometimes gets added there too, but if there's a lot of it then it's frequently kept elsewhere to prevent README from getting overwhelming for end users and random people just checking out the project.
  - blinkymach12 1y ago
    I don't think anything requires a README.md to be monolithic. They often provide the introductory material that you mention here, then link out to other appropriate files for contribution guidelines, etc.
- sothatsit 1y ago
  It should not contain personal preference. It should contain project conventions. Project guidelines, how to build your project, where to find or implement different types of features, are not personal preference. If different members of your team disagree on these things, that is a problem.