I tend to include a well documented justfile, so between the readme and that common commands are covered. If there’s a style guide it should be its own file, or summarized in the readme.
If Claude is making errors I tend to just update my global Claude file, but I haven’t updated it in 6 months — only to disable Claude signatures on generated commit messages.
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.
otherwise it's like leaving vim dotfiles in the repo or something
Its critical that its part of the source code.
They often describe:
- Overall architecture
- Repository layout
- Processes to use
- Things not to do: code styles to avoid, libraries to not use, etc.
While they’re primarily documenting these things for an agent, the information is similarly useful to a human.
The number one reason is, you are on a 10-dev tea and it just doesn't make sense for everyone to waste their token budget creating separate instances of this file, which an also requires ingesting the othe whole repo... That is 50, 60%.
The other bit is that you have a review pipeline hooked into CI/CD, and it is the easiest way to tell the bot how to review your code.
I used to be a purist about IDE configurations, but if everyone isn't on the same page about formatting and stuff like that you see a lot of file churn as things move around.
I would have said the same thing about the .github/ folder, but I've had to add things to it to prevent Copilot from thinking bad patterns in existing code are actually good patterns that should be repeated.
It makes more sense when your communication between teammates is constrained to the repository, because your other communication channels are already saturated. They're meta concerns that really have nowhere to go outside the repository without getting lost.
IMO that is what automated static analysis jobs are for. Let me configure my IDE how I want.
VS Code is one notorious offender in that realm; it will try to commit settings.json, even if their gitignore's are set up to ignore all other cruft.
In general, the question of what should go in the source folder is a bit of a mess. Source code, README and License make enough sense, but what about files describing project governance or CI configuration logic? Or what about files that are used to make the forge you're using render the repository in a certain way (for example: bug tracker templates). Those are all cruft insofar that they have nothing to do with code, but it's generally agreed on that you're supposed to commit those, maybe in a dot-folder if necessary.
Version control everything (inputs)
The idea of having to repeat something to your computer is ridiculous.
Also it looks like there's a compilation step to these files, which is interesting. The raw file was included, not the environment specific file.
And tests, linter configuration, doc...
If you want private stuff you use CLAUDE.local.md
I look at all those files the same way as IDE configuration cruft--it's workstation-specific configuration that shouldn't even go into source control. I would .gitignore all of those files. Is this not what is done in industry?
EDIT: Wow, thanks for all the replies. Very eye-opening to see what's happening outside of my hobby-experimentation with the technology. I was coming at it with the assumption that 1-2 out of 20 people on the team were using CLAUDE.md, so why have it in source control. But if all 20 people are using it, I can see the benefits. This reply chain has really opened my eyes, thank you HN.