1In one sentence
A small text file named CLAUDE.md in your project folder tells Claude Code how you like things done, and it reads it at the start of every session.
2New words
- CLAUDE.md — a plain text file (the .md means Markdown, simple formatted text) with your project's rules, conventions and useful commands. Think of it as Project instructions (Chapter 1.5) for Claude Code.
- Convention — a habit your project follows: how files are named, which language, how to run tests.
- Scope — where a rule applies. There can be a CLAUDE.md for your whole computer (your personal habits), one per project (the project's rules), and one for a company.
3Why you would want it
Without it, every session starts with Claude guessing your style, and you correct the same things again and again. With it, Claude knows the test command, the naming rules and the parts not to touch before it writes a line. Teams share one file so every member gets the same Claude.
4Try it now
(paid plans)
- In your project folder, ask Claude Code: Create a CLAUDE.md for this project with: what the project is in two lines, how to run it, how to test it, the naming rules we use, and three things you must never change without asking.
- Read the file it writes; fix anything wrong.
- Start a new session and ask for a small change. Notice it runs the tests and follows the naming rule without being told.
5What you will see
[Picture pending: a CLAUDE.md open in the editor and a session following it.] A short file, usually under a page, that Claude mentions when it starts ("Following CLAUDE.md: running tests after changes"). It works alongside your global rules; a project file adds to them.
6Watch out
- Keep it short and current. A long, stale CLAUDE.md is worse than none; Claude will follow outdated rules faithfully.
- Put secrets (passwords, keys) nowhere near it. It is a text file that gets shared.
7Go further
Add a line like When unsure, ask before changing more than three files. Chapter 6.3 turns repeated jobs into skills, which are rules with steps.