I counted this morning: 46 CLAUDE.md files on my machine
It started with an Instagram reel showing a Claude Code project-structure diagram. Nicely drawn, widely shared: CLAUDE.md, .mcp.json, then .claude/ opening out into settings, rules, commands, skills, agents, hooks. My first reaction was not that I had learnt something. It was that the diagram is where I was a year ago.
The folder tree is the easy part. Making the directories takes five minutes.
What actually turned this from a good chat window into something that carries work is three things the diagram cannot show.
The first is what runs when nobody is typing. I have fourteen hook events wired: session start, prompt submitted, before a tool runs, after a tool fails, when a subagent finishes, when a task completes. None of those are things I ask for. They fire on their own. The diagram gets as far as a hooks/ folder and stops, but the folder was never the point. When it fires is the point.
The diagram gets as far as a hooks/ folder and stops, but the folder was never the point.
The second is memory. Two hundred and ninety-two files, one fact each, surfacing by relevance rather than by me remembering to mention them. Without that layer, every new session began with me re-explaining who I am and what I am working on.
The third took me a long time to admit.
I used to think a more detailed CLAUDE.md was a better one. So it grew. It is 219 lines now. The result was the opposite of what I expected: the more I wrote, the less of it was followed. Not out of laziness. In a 219-line file every rule flattens into the same rule, and nothing reads as more important than anything else. What fixed it was moving rules out into skills that load only when the work is relevant, and giving every principle a counter-example. A principle on its own gets followed about half the time.
So the diagram is not wrong. It is drawing the foundations. Foundations do not do any of the work.
