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.
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.
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.
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.
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.
1 reply →