Writing a good Claude.md
humanlayer.dev730 points by objcts 2 days ago
730 points by objcts 2 days ago
> Claude often ignores CLAUDE.md
> The more information you have in the file that's not universally applicable to the tasks you have it working on, the more likely it is that Claude will ignore your instructions in the file
Claude.md files can get pretty long, and many times Claude Code just stops following a lot of the directions specified in the file
A friend of mine tells Claude to always address him as “Mr Tinkleberry”, he says he can tell Claude is not paying attention to the instructions on Claude.md, when Claude stops calling him “Mr Tinkleberry” consistently
That’s hilarious and a great way to test this.
What I’m surprised about is that OP didn’t mention having multiple CLAUDE.md files in each directory, specifically describing the current context / files in there. Eg if you have some database layer and want to document some critical things about that, put it in “src/persistence/CLAUDE.md” instead of the main one.
Claude pulls in those files automatically whenever it tries to read a file in that directory.
I find that to be a very effective technique to leverage CLAUDE.md files and be able to put a lot of content in them, but still keep them focused and avoid context bloat.
Ummm… sounds like that directory should have a readme. And Claude should read readme files.
READMEs are written for people, CLAUDE.mds are written for coding assistants. I don’t write “CRITICAL (PRIORITY 0):” in READMEs.
The benefit of CLAUDE.md files is that they’re pulled in automatically, eg if Claude wants to read “tests/foo_test.py” it will automatically pull in “tests/CLAUDE.md” (if it exists).
If AI is supposed to deliver on this magical no-lift ease of use task flexibility that everyone likes to talk about I think it should be able to work with a README instead of clogging up ALL of my directories with yet another fucking config file.
Also this isn’t portable to other potential AI tools. Do I need 3+ md files in every directory?
> Do I need 3+ md files in every directory?
Don’t worry, as of about 6 weeks ago when they changed the system prompt Claude will make sure every folder has way more than 3 .md files seen as it often writes 2 or more per task so if you don’t clean them up…
Strange. I haven’t experienced this a single time and I use it almost all day everyday.
That is strange because it's been going on since sonnet 4.5 release.
I also have seen this happen since then, but I actually like it. The .md files never make it into a commit, but they are quite handy for PR drafts.
I wonder if it's because I have instructions for Claude to add comment blocks with explanations of behavior, etc that it can self reference in future. I guess that is filling the role that these .md files would.
Is your logic that unless something is perfect it should not be used even though it is delivering massive productivity gains?
> it is delivering massive productivity gains
[citation needed]
Every article I can find about this is citing the valuation of the S&P500 as evidence of the productivity gains, and that feels very circular
What kind of citation or evidence would you expect? How would you measure productivity gains? From my personal life and activities however it is very clear. I have simply been able to do so many things I would have never been able to do without AI.
> How would you measure productivity gains?
I'm not entirely sure - certainly anecdotes abound (as do anecdotes to the contrary).
I am however sure that when someone claims that a technology is world-changing, and that it has already led to significant productivity gains... the onus is on them to provide evidence for such claims
I feel similarly, but the other guy's point is still good; there is no empirical evidence that AI is really as helpful as we think, and there is empirical evidence that among those who perceive productivity gains, most are wrong and the rest are overestimating the effect.
Our experiences don't agree with the established facts, but the plural of "anecdote" is not "data."
It’s not delivering on magical stuff. Getting real productivity improvements out of this requires engineering and planning and it needs to be approached as such.
One of the big mistakes I think is that all these tools are over-promising on the “magic” part of it.
It’s not. You need to really learn how to use all these tools effectively. This is not done in days or weeks even, it takes months in the same way becoming proficient in eMacs or vim or a programming language is.
Once you’ve done that, though, it can absolutely enhance productivity. Not 10x, but definitely in the area of 2x. Especially for projects / domains you’re uncomfortable with.
And of course the most important thing is that you need to enjoy all this stuff as well, which I happen to do. I can totally understand the resistance as it’s a shitload of stuff you need to learn, and it may not even be relevant anymore next year.
While I believe you're probably right that getting any productivity gains from these tools requires an investment, I think calling the process "engineering" is really stretching the meaning of the word. It's really closer to ritual magic than any solid engineering practices at this point. People have guesses and practices that may or may not actually work for them (since measuring productivity increases is difficult if not impossible), and they teach others their magic formulas for controlling the demon.
Most countries don’t have a notion of a formally licensed software engineer, anyway. Arguing what is and is not engineering is not useful.
Most countries don't have a notion of a formally licenses physicist either. That doesn't make it right to call astrology physics. And all of the practices around using LLM agents for coding are a lot closer to astrology than they are to astronomy.
I was replying to someone who claimed that getting real productivity gains from this tool requires engineering and needs to be approached as such. It also compared learning to use LLM agents to learning to code in emacs or vim, or learning a programming language - things which are nothing alike to learning to control an inherently stochastic tool that can't even be understood using any of our regular scientific methods.
I think it's relevant when people keep using terms like "prompt engineering" to try and beef up this charade of md files that don't even seem to work consistently.
This is a far far cry from even writing yaml for Github/Gitlab CICD pipelines. Folks keep trying to say "engineering" when every AI thread like this seems to push me more towards "snake oil" as an appropriate term.