After weeks of debugging frustrating Claude Code sessions, I traced most problems to missing rules. Three rules in CLAUDE.md fixed the majority of them.
Rule 1: Minimal footprint
Minimal footprint. Only modify files directly required for the stated task. Do not refactor adjacent code, add comments to files you didn't change, or fix issues outside your scope. Note additional problems as TODO comments, do not implement fixes.
This stops the "while I'm in here" behavior. Before adding this, a simple bug fix would sometimes touch 6-8 files. After: 1-3.
Rule 2: No silent errors
Never silently catch exceptions. Always log the full error with context (include relevant IDs, paths, or state) and either re-throw or return an error object the caller can act on. An empty catch block is a bug.
I spent hours debugging a production issue that turned out to be swallowed by a bare except: pass. Claude had added it while handling an edge case. This rule stops that.
Rule 3: Verify before claiming done
Do not say work is complete until you have run the tests and confirmed they pass. Show the test output before marking any task complete. If tests don't exist for the changed code, write them first.
The "I've implemented X" message with no verification was costing me 30 minutes per session finding the gaps. This rule means Claude doesn't finish until the tests pass.
What these three have in common
They address Claude's default behaviors, not its capabilities. Claude isn't incapable of writing focused diffs, handling errors, or running tests. It just doesn't do these by default unless you make them explicit rules.
Three sentences in CLAUDE.md. The sessions after adding them were noticeably cleaner.
Top comments (0)