How to write a CLAUDE.md (with a real example)

Put CLAUDE.md in your project’s root folder for instructions about that project. Put it at ~/.claude/CLAUDE.md for personal instructions across projects. It’s a plain Markdown file that Claude Code reads for context when you work.

Start with the things you keep having to explain: how to run the project, how to check a change, and what Claude should know before editing. You can read my global file here.

Where does CLAUDE.md go?

You want instructions for…	Put the file here
Everyone working in one project	`CLAUDE.md` in the project root; commit it with the code
Your preferences across projects	`~/.claude/CLAUDE.md` on macOS/Linux, or `C:\Users\<YourName>\.claude\CLAUDE.md` on Windows
Your own notes for one project	`CLAUDE.local.md` in the project root; add it to `.gitignore`

Claude Code also supports .claude/CLAUDE.md for shared project instructions. The official documentation explains the other locations and how files load. These instructions guide Claude; they don’t enforce permissions.

A starter you can copy

Create CLAUDE.md in your project and adapt this. Replace the bracketed parts with facts from your repository before using it.

# Project
[What this project does and who uses it.]

## Commands
- Start locally: [command]
- Check a change: [test, lint, or build command]

## Where things live
- [Folder]: [what belongs here]
- Read [design or architecture document] before changing [area].

## Working rules
- Confirm the problem before changing the code.
- Follow the patterns already used in this project.
- Preserve unrelated work in the checkout.
- Run the relevant checks and report anything you couldn't verify.

You can also run /init in Claude Code to generate a starting file from the repository. Review its commands and assumptions before keeping them. Use /context to check which memory files loaded.

How long should it be?

Start with a screenful. My rule of thumb is that each line should prevent a mistake or save an explanation. Keep project commands in the project file and your general preferences in the global file.

When a section grows into a manual, link to the existing project documentation. Keep only the instruction about when to read it. Revisit the file when a command changes or an instruction repeatedly fails to help.

My real example

I started from Jesse Vincent’s CLAUDE.md and have iterated since.

My global CLAUDE.md is here. It’s a worked example of personal instructions, not a file every project needs to copy. I often have Claude help curate the project-level file itself, then review what it proposes.

For example, mine asks Claude to search for existing functionality before adding code, read files before editing, and keep changes small. Those are habits I want across projects. A particular project’s build command belongs in that project’s file instead.

Mistakes to avoid

Copying someone else’s whole file without reading it. Their commands, preferences, and tradeoffs may be wrong for your project.
Vague instructions. “Write good code” gives less direction than a real check command or a pointer to an existing pattern.
Contradictory rules. Check the global and project files together when Claude keeps getting mixed signals.
Stale commands or secrets. Check commands against the repository, and keep credentials out of instruction files.

If you’re still figuring out what to ask the building session, the Cyrano Method gives you a second chat to work through that. For choosing among Google’s tools, I also wrote a Gemini field guide, which I keep current with a changelog at the bottom.