Comment by jedberg
2 days ago
The Claude MD is like the documentation you hand to a new engineer on your team that explains details about your code that they wouldn't otherwise know. It's not bad to need one.
2 days ago
The Claude MD is like the documentation you hand to a new engineer on your team that explains details about your code that they wouldn't otherwise know. It's not bad to need one.
But that documentation shouldn’t need to be updated nearly every other day.
Consider that every time you start a session with Claude Code. It's effectively a new engineer. The system doesn't learn like a real person does, so for it to improve over time you need to manually record the insights that for a normal human would be integrated by the natural learning process.
Yes, that's exactly the problem. There's good reasons why any particular team doesn't onboard new engineers each day, going all the way back to Fred Brooks and "adding more people to a late project makes it later".
Reminds me of that Nicole Kidman movie Before I Go to Sleep.
there are many tools available that work towards solving this problem
Sleep time compute architectures are changing this.
I certainly could be updating the documentation for new devs very frequently - the problem with devs is that they don't bother reading the documentation.
and the other problem - when they see something is wrong/out of date, they don't update it...
If you are consistent with how you do your projects you shouldn't need to update CLAUDE.md nearly every day. Early on, I was adjusting it nearly every day for maybe a couple of projects but now I have very little need to make any adjustments.
Often the challenge is users aren't interacting with Claude Code about their rules file. If Claude Code doesn't seem to be working with you ask it why it ignore a rule. Often times it provides very useful feedback to adjust the rules and no longer violate them.
Another piece of advice I can give is to clear your context window often! Early in my start in this I was letting the context window auto compact but this is bad! Your model is it's freshest and "smartest" when it has a fresh context window.
It takes a lot of uncached tokens to let it learn about your project again.
Same thing happens every time a new hire joins the team. Lots of documentation is stale and needs updating as they onboard.
But that documentation shouldn’t need to be updated nearly every other day.
It does if it’s incomplete or otherwise doesn’t accurately convey what people need to know.
And something is terribly wrong if it is constantly in that state despite near daily updates.
Why not?
Have you never looked at your work's Confluence? Worse, have you never spent time at a company where the documentation wasn't frequently updated?
Do you have nothing but onboarding material on yours and somehow still need to update it several times a week?