alt Hacker NewsThis 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.
Replies
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.
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.