Comment by mexicocitinluez
4 days ago
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.
> Because it's all very clearly spelled out within the code itself.
You're probably burning tokens. A markdown file with a summary, structure of your project, rules, and even goals prevents Claude from hunting for and reading files over and over. Each new session (or after compact) would be starting from scratch. I take it a step further and create a HANDOFF.md file between compacting that gives the next session full context of what was done and how to continue.
Also:
"Treat CLAUDE.md as the place you write down what you’d otherwise re-explain. Add to it when:
Claude makes the same mistake a second time
A code review catches something Claude should have known about this codebase
You type the same correction or clarification into chat that you typed last session"
https://code.claude.com/docs/en/memory#claude-md-files
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 shouldn't have been so hyperbolic. I do have some general statements about tone and not to go down follow-up question rabbit holes and when to push back or not to install dotnet while on WSL and just go through Windows. Anything that won't change based on day-to-day dev work.
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.
> the logic being you don't want to do that every time for every prompt
That's definitely a downside of a minimal MD and I could def be wasting tokens. I've tried to scope the tasks such that it won't feel the need to scan unnecessary files, but it's not bulletproof.
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.
[dead]
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.
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.