The Coding Guidelines CLAUDE.md
Four rules that stop AI from overcomplicating, over-editing, and guessing
The Idea
AI coding tools are fast, but left to their own devices they make the same handful of mistakes over and over. A CLAUDE.md is a plain-text file Claude reads before it touches your code — think of it as a standing set of house rules.
This one is short and does one job: it bakes in the habits of a careful senior engineer. Think first, keep it simple, change only what you were asked to, and prove it works before saying it's done.
It's aimed at the usual suspects
- →It writes 200 lines when 50 would do.
- →It "helpfully" refactors code you didn't ask it to touch.
- →It guesses at what you meant instead of asking.
- →It adds config, flags, and abstractions for a one-off script.
- →It says "done" without ever checking that it actually works.
Install It (No Terminal Needed)
The easiest way: let Claude set it up for you. Open a new chat — in Claude Code or on the web at claude.ai — and paste this in. Claude grabs the file and either drops it into your project or merges it into a CLAUDE.md you already have.
Prefer to do it by hand? Drop the CLAUDE.md in the root of your project, or put it at ~/.claude/CLAUDE.md to apply it across every project you build with Claude Code.
The Four Rules
The whole file is four short sections. Each one targets a specific failure mode, and together they bias Claude toward caution over speed — which is exactly what you want on anything that isn't trivial.
Think Before Coding
Don't assume — askState assumptions out loud. If there are multiple interpretations, present them instead of silently picking one. If a simpler approach exists, say so. If something's unclear, stop and ask before writing a line.
Simplicity First
Minimum that worksThe least code that solves the problem, nothing speculative. No features you didn't ask for, no abstractions for single-use code, no error handling for impossible cases. If 200 lines could be 50, it gets rewritten.
Surgical Changes
Touch only what you mustNo "improving" adjacent code, no refactoring things that aren't broken, no reformatting on the way past. Match the existing style even if you'd do it differently. Every changed line should trace back to what you actually asked for.
Goal-Driven Execution
Define done, then verifyTurn vague tasks into verifiable goals. "Fix the bug" becomes "write a test that reproduces it, then make it pass." Strong success criteria let Claude loop on its own instead of checking in after every step.
How You Know It's Working
You won't see a banner or a status message — the change shows up in the diffs. Smaller, tighter changes. Fewer rewrites because something got overcomplicated. And clarifying questions arriving before the work starts instead of apologies after a mistake.
One honest caveat: these guidelines lean toward caution over raw speed. On a throwaway one-liner that's overkill — Claude is told to use judgment there. On anything real, it's the trade you want.
Give Claude better habits.
Drop it in once and every build after that gets a more careful engineer. Read the file, copy it, or fork it on GitHub.
View the CLAUDE.md on GitHub →Based on the CLAUDE.md from multica-ai/andrej-karpathy-skills. This is the same file, packaged to be easy to find, install, and share.