Every AI coding tool has the same problem: it doesn't know you. It doesn't know your project. It doesn't know you spent three hours last Tuesday debugging a hydration mismatch and you'd really prefer not to do that again.
CLAUDE.md fixes this. It's a markdown file that Claude Code reads at the start of every conversation. Think of it as a briefing document. You write the rules once, the AI follows them every time.
I've been refining mine across 9 projects and hundreds of sessions. Here's what I've learned about what actually matters in that file.
Two Levels: Global and Project
Claude Code supports two CLAUDE.md files that layer on top of each other:
- Global (
~/.claude/CLAUDE.md): Rules that apply to every project. Security practices, communication preferences, how you like to work. - Project (in your repo root): Architecture context, tech stack decisions, commands, project-specific patterns.
The global file is where you put "always do this" rules. The project file is where you put "here's what this codebase looks like." They combine automatically. You write each piece once and it just works.
Security Guidelines: The Non-Negotiable Section
This was the first section I wrote and it's the one I'm most glad exists. AI coding tools will happily put an API key in client-side code if you don't tell them not to.
My security section covers five areas:
| Area | Key Rule | Why It's There |
|---|---|---|
| Input/Output | Sanitize all inputs, vague error messages | Prevent injection, don't leak internals |
| Secrets | Keep everything server-side | "If it's on their screen, it's in their pocket" |
| Architecture | Use middleware, server-side validation | Don't let the frontend talk directly to the database |
| Access Control | Verify every request, rate limit everything | One auth check at login isn't enough |
| Maintenance | Keep deps updated, audit with a second AI | Old packages have known exploits |
None of this is revolutionary security advice. The point is that it's always loaded. I don't have to remember to say "hey, don't put the Supabase key in the React component" because the rule is already there. The AI just follows it.
The "audit with a second AI" rule is one of my favorites. After building something with Claude, I'll sometimes paste the code into a different model and ask it to find vulnerabilities. They catch each other's blind spots more often than you'd expect.
Working Guidelines: Teaching the AI How You Think
This section took the most iteration to get right. It's not about code. It's about behavior.
A few of the rules that made the biggest difference:
"Understand Before Acting" sounds obvious. But without this rule, AI tools will confidently refactor a file they haven't read. I've watched it happen. Now the first thing Claude does is read the relevant files before touching anything.
"No Speculation" is the hallucination guard. The rule says: never make claims about code you haven't opened. If I ask "what does the content loader do?" the AI reads content.ts first instead of guessing. This single rule eliminated maybe 80% of the moments where I'd catch the AI confidently describing code that doesn't exist.
"Simplicity First" counteracts the AI's natural tendency to over-engineer. Left to its own devices, Claude will add error handling for scenarios that can't happen, create abstractions for one-time operations, and build configuration systems for things that have exactly one value. The rule is blunt: make every change as simple as possible, impact as little code as possible, everything is about simplicity.
"Incremental Development" is the one that saved me the most time. Every change should result in code that compiles and runs. Build in small increments. Test before moving on. Without this, the AI will sometimes make twelve changes across eight files and hand you a project that doesn't build. With it, each step works before the next one starts.
Project Context: The Architecture Briefing
The project-level CLAUDE.md is where things get specific. For this site, it includes:
- What the project is (one sentence)
- Current phase (Sprint 11, 9 apps, 21 journal entries)
- Key decisions with "Do Not Revisit" in the heading (tech stack, hosting, content approach)
- Architecture summary (how MDX gets compiled, how SSG works, deployment flow)
- Project structure (directory tree with annotations)
- Key patterns (hydration fixes, theme handling, date formatting gotchas)
- Commands (dev, build, test, image generation scripts)
The "Do Not Revisit" section is critical. Without it, the AI will periodically suggest switching from Tailwind to styled-components or from Cloudflare to Vercel. It's trying to be helpful. But some decisions are settled and reopening them wastes everyone's time.
The key patterns section is where hard-won knowledge lives. Things like "FadeIn component skips animation for elements already in viewport at mount time" or "all toLocaleDateString calls use timeZone: UTC to prevent hydration mismatch." These are bugs I already found and fixed. The CLAUDE.md makes sure the AI doesn't reintroduce them.
What Changed After Adding All This
Before CLAUDE.md, every conversation started from zero. I'd explain the project, remind the AI about security, ask it to read files before changing them, tell it not to over-engineer. Every. Single. Time.
Now I just say what I want to build.
The AI already knows the tech stack. It knows the file structure. It knows to read before writing. It knows to keep changes small. It knows not to put secrets in client code. It knows about the hydration bugs.
The conversations got shorter. The code got better on the first try. The number of "wait, why did you do that" moments dropped significantly.
Start Small
You don't need to write a comprehensive CLAUDE.md on day one. Start with three things:
- One security rule you care about (mine was "keep secrets server-side")
- One behavior rule that would save you the most repeated corrections (mine was "read before writing")
- One project context line describing what you're building
Then add to it every time the AI does something you have to correct. If you find yourself saying the same thing twice, that's a CLAUDE.md entry. The file grows naturally from your actual pain points.
After a few sessions, you'll have a document that makes every future session better. That's the whole trick.