[theshrike79]

README.md should be for humans CLAUDE.md for machines.

Most agents use README as a storage for EVERYTHING related to the project by default, which is annoying for humans who just want to figure out a) what the thing does b) how to install it. Then you start reading and there's some intricate documentation on how data flows through the application etc.

If you're only working on your personal projects with no collaborators, just a global claude file is just fine. Per-project files are more for things that are specific to that project.