Recently, I came across this thread from the creator of Claude Code: https://x.com/bcherny/status/2007179832300581177
While I find much of his advice useful, there’s one point that I don’t agree with based on my own experience: putting coding rules into CLAUDE.md.
I have used Claude Code since its launch, and this could just be an impression carried from past experience when early verions of Claude Code didn’t follow CLAUDE.md reliably. But when I really think about why we’re putting coding rules into CLAUDE.md in the first place, it reminds me of an advice from my boss:
Don’t rely on habits, rely on systems.
LLMs, though have advanced a lot, are still non-deterministic. It’s in their nature. I believe they will progressively get better, but they can never be more deterministic than a system built to ensure so.
Instead of writing in CLAUDE.md: “Make sure the code doesn’t have type errors”, we should write a stop hook that directly runs a command to type check instead. We should build systems to help AI agents do their best work: run lint after they write code, run typecheck before they commit, write a hook to audit their code for security issues, etc.
These measures are more effective than adding another bullet point to CLAUDE.md because they’re guaranteed to be run. CLAUDE.md represents the good habits we ask our AI agents to follow, but we cannot guarantee they will.
Therefore, CLAUDE.md, in my opinion, should be really short. It should be reserved for things we can’t systemize yet. Whenever we think of adding a new bullet point to CLAUDE.md (or AGENTS.md), let’s spend a moment to think whether we can systemize that instead, and use CLAUDE.md/AGENTS.md as the last resort.