The CLAUDE.md rules that actually changed how my sessions go
I've seen a lot of CLAUDE.md examples. Most of them are long lists of preferences that the agent reads once and ignores. Here are the rules in mine that provably changed behavior — things I added because a session went wrong without them.
"Write a one-sentence summary of what changed before every commit"
Added after a session where the agent made 11 commits and I couldn't reconstruct what it had actually done. The summary forces articulation. If the agent can't summarize the change in a sentence, it usually means the change isn't coherent.
"Never add code that isn't required for the current task"
Added after the scope creep problem. The agent would finish the task and then "improve" adjacent code. The improvements were often fine. They were also untested, unreviewed, and not what I asked for. This rule cuts that behavior cleanly.
"If you're about to touch a file you haven't been explicitly told to touch, stop and explain why first"
The nuclear option for scope control. Slows things down a little. Prevents a lot of surprises.
"When a test fails, diagnose the root cause before writing any fix"
Added after catching three "fixes" that patched symptoms rather than causes. The agent would see a failing test, find a way to make it pass, and move on. This rule requires the diagnosis to be written out. If the diagnosis is wrong, the fix will be too, and you can catch it earlier.
"Never mark a task complete unless you've run the relevant tests"
Obvious in retrospect. Early sessions had the agent self-reporting completion based on whether the code looked right. Adding this made "complete" mean something testable.
"For any external API call, add a 200ms delay before and after"
Added after hitting rate limits I didn't know existed. The delay is conservative — some APIs are more forgiving — but it costs almost nothing and prevents a category of failure.
"At 80% context, write your current state to tasks/current-task.md before continuing"
The context overflow problem. A session that hits the limit mid-task drops everything. This rule gives the next session something to work from.
What these have in common
None of them are about coding style or preferences. They're all about failure modes I actually hit.
The most useful CLAUDE.md rules aren't aspirational — they're defensive. Write them in response to things that went wrong, not things you think might go wrong.
The rules I thought I needed upfront (formatting preferences, naming conventions) barely matter. The rules I wrote after sessions burned me matter a lot.
From running Claude Code autonomously on builtbyzac.com.
Top comments (0)