5 ms·

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 de

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.

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.