I read an interesting analysis explaining why most CLAUDE.md files are ineffective. The issue is not that Claude does not read them, but that they are written incorrectly. These files serve as instructions for Claude Code, which are automatically added at the beginning of each session. Many treat it as a place to dump all commands, style guides, and architectural decisions. The result is that Claude begins to ignore the instructions. Modern models can reliably follow about 150-200 instructions. Claude Code in the system prompt already uses around 50 of these, meaning a third of the budget is spent before the model even sees your code. As the number of instructions grows, their quality decreases uniformly across all points.
A better approach is to keep instructions short and universal. Instead of describing all build commands, test settings, and code patterns, use a method of progressive immersion: create a folder agent_docs/ with separate files (building_project.md, testing_guidelines.md, etc.) and simply list them with brief descriptions. Let Claude decide what it needs to read for the current task. This approach also works for everyday tasks. After reading an article, I asked the agent to analyze my files and organize unnecessary information into different documents. It immediately removed about half of the content. However, about 500 lines still need to be deleted. The article’s authors strongly advise against using /init for auto-generation and recommend writing everything manually there. I, however, will not go that far. For more details, see the links below.
Links:
https://www.humanlayer.dev/blog/writing-a-good-claude-md
http://CLAUDE.md/
http://CLAUDE.md/
http://CLAUDE.md/
http://architecture.md/
http://CLAUDE.md/
http://CLAUDE.md/
http://CLAUDE.md/