You install Claude Code, you ask it to fix a bug, and it rewrites half your project. You repeat the same instruction three times a day. The problem is almost never the model: it's that it knows nothing about your project or the way you work at the moment you open the terminal.

That's exactly what the CLAUDE.md file is for. It's a plain text file that Claude Code reads automatically at the start of every session, before your first question. You write down your rules, your tech stack, your test commands, your hard limits. Written well, it turns a chatty assistant into a colleague who already knows the house.

You'll see where to put it, how to create it (three methods), the seven writing rules that decide whether an instruction gets followed or ignored, a complete example you can copy, and how to check that Claude Code is really obeying. No advanced development skills required: a text editor is enough.

What the CLAUDE.md File Actually Does

The CLAUDE.md file is a permanent memo that Claude Code loads into its working memory at the start of every session, without you having to paste it in yourself.

The difference from an instruction typed into the chat is simple: your chat instruction applies to one conversation, CLAUDE.md applies to all of them. If you write “always run the tests before saying you're done” in the file, the rule applies on Monday and on Thursday, in a brand-new session, without you thinking about it.

In practice, four families of information belong there:

  • Project context: what the app does, who uses it, what the stack is (language, framework, database).
  • Useful commands: how to install dependencies, run tests, start the server, format the code. Claude Code wastes a lot of time guessing these commands if it doesn't have them.
  • Conventions: file naming, commit style, folder structure, the language comments are written in.
  • Hard limits: what it must never do (touch the production folder, modify auto-generated files, install a new dependency without asking).

One thing a lot of people discover too late: every line in this file is re-read every session and eats part of your context budget. A vague 400-line CLAUDE.md is less effective than a precise 80-line one. Being concise isn't a stylistic preference here, it's a technical constraint.

If you're brand new to the tool, start with the Claude Code tutorial for beginners and then come back here: CLAUDE.md makes far more sense once you've run your first few sessions.

Where to Put Your CLAUDE.md File (and Which One Wins)

You can have a CLAUDE.md in several places at once: they stack, and the one closest to the code you're changing carries the most weight.

Location Scope When to use it
~/.claude/CLAUDE.md All your projects Your personal working preferences (language, response style, habits)
CLAUDE.md at the project root The whole team Stack, commands, conventions, hard limits. Versioned with Git
CLAUDE.md in a subfolder That folder Rules specific to one part of the code (API, front end, scripts)

The file at the project root is the one that matters most. Because it's versioned along with the rest of the code, the whole team works from the same rules, and a newcomer inherits the context just by cloning the repo.

Two shortcuts worth knowing right away. The /memory command opens your memory files so you can edit them straight from the terminal. And by starting a message with the # character, you're asking Claude Code to add the rule to the file of your choice itself: handy for capturing an instruction at the exact moment you think of it. You can also import another file into your CLAUDE.md with the @path/to/file.md syntax, which is useful for avoiding duplication of documentation you already have. The locations and the full syntax are covered in the official Claude Code memory documentation.

When two files contradict each other, the more specific rule wins in practice. Still, try not to contradict yourself: if your personal file says “answer in English” and the project file says “answer in French”, you'll get unstable results from one session to the next.

Three Ways to Create Your CLAUDE.md File

You can learn with structured guidance, let Claude Code generate a first draft with its built-in command, or start from a blank page. All three work, they just don't ask for the same amount of time or the same starting level.

Method 1: Train with Skilzy

This is the fastest route if you're starting from zero and want a file that holds up from week one. The Claude Code and vibe coding program from Skilzy walks you through building your CLAUDE.md on your own project, step by step: installation, first sessions, writing the rules, checking that they're actually followed. You're not copying a generic template, you're writing your own.

The concrete advantage is the built-in AI Lab: you use the real AI tools right from the platform, credits included, without stacking up subscriptions while you learn. Skilzy covers more than 15 programs (images, video, music, automation with n8n, prompt writing, coding with AI) and offers two state-recognized, fundable certifications: RS7439 in AI content marketing and RS6792 in AI and sales. Access starts at €29.90 per month, no commitment.

To try before you pay, the discovery demo gives you 7 days with 1 image, 1 video, 1 music track and 10 messages, no credit card. You create an account, that's it.

Method 2: Claude Code's /init Command

Claude Code can generate a first CLAUDE.md on its own. You open the terminal at your project root, launch Claude Code, type /init and confirm. It walks the file tree, spots the stack, the available scripts and the visible conventions, then writes a file at the root.

It's free, instant, and an excellent starting point. Its limits are real: the generated file describes what it sees, not what you want. It doesn't know your hard limits, the traps in the project, or the fact that a given folder must never be touched. Treat /init as a draft to read line by line and complete by hand. The command is one of the 20 Claude Code commands worth knowing if you want the rest of the picture.

Method 3: Write the File by Hand

You create a file named CLAUDE.md at your project root with your editor, and you fill it in. This route takes the most reflection, but it produces the cleanest file, because every line is there for a reason you can explain. It's also the right approach for an unusual project, where the structure /init detects automatically would be misleading.

In practice, most people combine the two: /init for the skeleton, then a cleanup by hand.

The Seven Writing Rules That Make the Difference

An instruction gets followed when it's short, imperative and verifiable; it gets ignored when it reads like a general intention.

  1. One rule per line, in the imperative. “Run npm test before declaring a task finished” works. “Ideally we should keep quality in mind” says nothing actionable.
  2. Make every rule verifiable. Put in file names, numbers, exact commands. “Keep components under 200 lines” is measurable, “write short components” isn't.
  3. Say what to do, not just what to avoid. Replace “don't use concatenated SQL queries” with “always use parameterized queries”. A positive instruction gives a direction; a ban on its own leaves the field wide open.
  4. Give the project's real commands. Install, tests, lint, build, local start. This is the section that saves the most time, because it removes the trial and error at the start of a session.
  5. Put absolute prohibitions at the top, in a short section. Three to five lines maximum, clearly marked. Buried in the middle of forty recommendations, they slip through the cracks.
  6. Keep the file short. Aim for 50 to 150 lines. Beyond 250, you dilute your own priorities and burn context for nothing. If a section gets huge, move it into its own file and import it with @.
  7. Explain the why in half a line when a rule is counter-intuitive. “Never modify schema.generated.ts: it's regenerated on every build.” A short reason keeps the rule from being worked around with good intentions.

An Annotated CLAUDE.md Example

Here's a complete structure you can adapt to your own project in ten minutes.

Project: Online store (Next.js + Supabase)

Hard limits

  • Never touch the /migrations folder without my explicit approval.
  • Don't install any new dependency without asking me first.
  • Never commit an API key: use environment variables.

Commands

  • Install: pnpm install
  • Run locally: pnpm dev (port 3000)
  • Tests: pnpm test (Vitest)
  • Lint: pnpm lint --fix

Conventions

  • React components in PascalCase, one component per file.
  • Comments and commit messages in English.
  • Commit messages in the format type(scope): description.
  • Database calls go through lib/db.ts, never directly from a component.

How to work

  • Before a task with more than three steps, propose a plan and wait for my approval.
  • Run pnpm test before announcing that a task is done. If a test fails, say so with the output.
  • Make the simplest change that works. No refactoring I didn't ask for.

Four sections, about fifteen useful lines. You can start from this skeleton and replace each line with the reality of your project. Resist the urge to add everything that crosses your mind: add a rule the day you notice it's missing.

The Mistakes That Get Your Instructions Ignored (and How to Check)

Instructions that don't get followed almost always come from a file that's too long, too vague, or contradicted by another memory file.

The most common cases:

  • The epic novel. Three hundred lines of good intentions. Claude Code reads it all, but nothing stands out as a priority.
  • Untestable instructions. “Write professional-quality code” produces no observable behavior.
  • The file copied from another project. It references commands that don't exist, which triggers a cascade of errors at startup.
  • The file that's never updated. You switched package managers six months ago, and CLAUDE.md still says npm.
  • The global/project contradiction. Your personal file and the team's file are fighting over the same rule.

To check that everything is loading, three simple moves. Type /memory to see which files are actually being taken into account. Open a fresh session and ask: “Summarize in five points the instructions you follow on this project.” If your main prohibition doesn't show up, it's in the wrong place or badly worded. Finally, run a trap test: ask for something that brushes up against a prohibition and see whether it stops to ask for confirmation.

One last important point: CLAUDE.md is an instruction, not a technical barrier. For rules that no lapse can be allowed to break (blocking a dangerous command, formatting systematically after every file write), go through the Claude Code hooks mechanism, which runs deterministically, and through the settings described in the settings and permissions documentation.

Final Word

A good CLAUDE.md is built in small strokes: you start with fifteen lines, and every time you correct Claude Code twice on the same thing, you add the missing rule. After two weeks, you have a file that genuinely reflects how you work, and sessions where you repeat yourself three times less.

Start today: create the file, put in your three hard limits and your four commands. The rest will come on its own.