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've gone great lengths to make sure that my fairly complex domain can be understood by a person with little domain knowledge, which means it should certainly be understood by a tool that has a wealth of it.

I've found CLAUDE.md (etc.) make more sense when the agent is doing more generalized tasks rather than just coding.

If you're just having an agent produce code, then I'd agree. I'd argue that any additional context it might need ought to be included in README.md anyways, just like a human.

But I have projects where agents do more than just code, and retaining context about how I want the agents to operate, keeping track of gotchas, avoiding unnecessary steps in the future, etc., just ends up going into CLAUDE.md. It's not for me; it's for the agents. I also never edit this file directly. I may review it every once in a while to make sure there isn't anything weird in there, but I leave it to the agent to add what it thinks is necessary (or I'll tell it that something will be relevant in the future and that it should add it, etc.).

Although even this pattern isn't necessarily future-proof. Seems like skills are kind of taking that role. Still, I end up with a CLAUDE.md in these kinds of scenarios to catch all the little pieces of context that don't fit nicely anywhere else.

I had to create some workarounds to avoid this bug where they include a "this might not be relevant" preamble to the CLAUDE.MD file: https://github.com/anthropics/claude-code/issues/18560 - I ended up switching to Codex and it just straight up follows the AGENTS.MD instructions, it's nice to see.

This is to say, Anthropic seems to be going down the path you are describing to make the CLAUDE.MD unnecessary. But I think that's the Claude Code harness.

I think that's something that has changed in the last 6 months. It used to be standard practice to let Claude scan everything once and describe your repo in the CLAUDE.md - the logic being you don't want to do that every time for every prompt. But now I think the tooling has gotten so good at just grepping around your repos, and maintaining memory from previous sessions, that the best practice is only use CLAUDE.md for things that aren't obvious from the code.

I don't think that is controversial.

My system CLAUDE.MD spells out my preferences in stack and architecture, and how I expect the agent to interact with me.

I have it generate a summary doc in large repos so it doesn't need to slurp in the world to review a PR or work on a corner of it.

if i don't write "use podman instead of docker" it will go on journey to install docker. so there is some use for it.