This is definitely controversial, but I think the best CLAUDE.MD is no CLAUDE.MD at all. Every time I found myself wanting to put information into that file, I asked myself "Why isn't this already obvious from the code itself?" I don't need to tell the agent my tech stack, what DB access library I'm using, the way in which I write my tests, etc. Why? Because it's all very clearly spelled out within the code itself. I…
It is more like make the CLAUDE.MD file as small as possible. What is the least amount of info it needs to be more efficient for the repo. I think the best thing is to point out where important things are so Claude is not just reading random files.