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).
Also this isn’t portable to other potential AI tools. 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…
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.
There's no need for this level of performative ridiculousness with AGENTS.md (Codex) directives, FYI.
It's the difference between instructions for a user and instructions for a developer, but in coding projects that's not much different.
Sounds like a job for a CONTRIBUTING.md :)
claude.md seems to be important enough to be their very first point in that document.
