The 4 rules in my CLAUDE.md that fixed most of my bad Claude Code sessions

Robert Walaski — Tue, 13 Oct 2026 19:11:29 +0000

Claude Code is amazing for about a week. Then it refactors a file you didn't ask it to touch, over-engineers a five-line fix, or proudly announces "done" for something that doesn't work.

I use it daily on client projects, and almost every one of those moments traced back to a single idea:

The agent only knows what's in its context window right now.

Not what it "learned" yesterday. Not your team's conventions. If it isn't in the context, it doesn't exist. So the job isn't "prompting" - it's deciding what goes into the context and what stays out.

The cheapest, highest-impact place to start is your global ~/.claude/CLAUDE.md. Here are the four rules I put there.

Rule 1 - Think before coding

No silent assumptions. State what you're assuming. Surface tradeoffs.
Ask before guessing. Push back when a simpler approach exists.

Prevents the confident wrong turn: 300 lines built on an assumption you'd have corrected in five seconds.

Rule 2 - Simplicity first

Minimum code that solves the problem. No speculative features. No
abstractions for single-use code. If a senior engineer would call it
overcomplicated - simplify.

Prevents the "enterprise" reflex: interfaces with one implementation, config options nobody asked for.

Rule 3 - Surgical changes

Touch only what you must. Don't "improve" adjacent code, comments, or
formatting. Don't refactor what isn't broken. Match existing style.

The one that made my reviews roughly twice as fast. The diff is finally just the task.

Rule 4 - Goal-driven execution

Define success criteria. Loop until verified.

"Write the code" becomes "make this test pass, then verify it in the browser". It stops declaring victory early.

Why these work: constraints, not wishes

Most CLAUDE.md files are full of wishes: "Write clean, maintainable code following best practices." The model already thinks it does that. The sentence changes nothing.

A constraint is specific and checkable - by you and by the model. Add a reason and it becomes even stronger: the agent can apply the rule to situations you never listed, instead of dropping it under pressure.

Keep it short

Every line in CLAUDE.md is paid for in every session. My budget: under ~60 lines globally, under ~150 per project. Anything that's a procedure ("to release, first do X, then Y...") belongs in a skill, which only loads when needed.

And whenever the agent makes a mistake a reasonable newcomer would also make, add one line to a Gotchas section in the project file. Over months it becomes the most valuable document in the repo.

This is adapted from chapter 2 of my **Claude Code Field Manual* - 12 chapters on CLAUDE.md, permissions, skills, subagents, hooks and git flow, with every template as a copy-paste file.*

Free sample (chapters 1-2): https://robertwalaski.gumroad.com/l/claude-code-field-manual-free
Full manual + templates: https://robertwalaski.gumroad.com/l/claude-code-field-manual