You install Claude Code, 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 Claude Code 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 teammate who already knows the house.

You'll see where to put it, how to create it (three methods), the seven writing rules that make an instruction get followed instead of ignored, a complete example you can copy, and how to check that Claude Code is actually obeying. No advanced development skills needed: a text editor is enough.

What the CLAUDE.md File Is Really For

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 a task is 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 go in 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, language used for comments.
  • Hard limits: what it must never do (touch the production folder, edit 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 at every session and eats part of your context budget. A 400-line CLAUDE.md full of vague statements is less effective than an 80-line precise one. Being concise isn't a stylistic flourish 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 a lot more sense once you've run your first few sessions.

Where to Put Your CLAUDE.md (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 editing carries the most weight.

Location Scope When to use it
~/.claude/CLAUDE.md All your projects Your personal working preferences (language, answer 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 the exact moment you think of it. You can also import another file into your CLAUDE.md with the @path/to/file.md syntax, useful for avoiding duplication of documentation you already have. The locations and the full syntax are described 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 one says “answer in French”, you'll get unstable results from one session to the next.

Three Ways to Create Your CLAUDE.md

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 take the same amount of time or assume the same starting level.

Method 1: Learn with Skilzy

This is the fastest route if you're starting from scratch and want a file that holds up in your first week. The Skilzy Claude Code and vibe coding program has you build 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 perk 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 certifications recognized by the French government and eligible for funding, 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. 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, though: the generated file describes what it sees, not what you want. It doesn't know your hard limits, the project's traps, or the fact that one particular 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 a very unusual project, where the structure /init auto-detects would be misleading.

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

The Seven Writing Rules That Make the Difference

An instruction gets followed when it's short, imperative and checkable; 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. “It would ideally be good to think about quality” says nothing actionable.
  2. Make every rule checkable. Use 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 direction; a bare prohibition leaves the field open.
  4. Give the project's real commands. Install, tests, lint, build, local startup. This is the section that saves the most time, because it removes the trial and error at the start of a session.
  5. Put the absolute prohibitions at the top, in a short section. Three to five lines maximum, clearly labeled. Buried in the middle of forty recommendations, they get lost.
  6. Keep the file short. Aim for 50 to 150 lines. Past 250, you dilute your own priorities and burn context for nothing. If a section gets huge, move it into a dedicated file and import it with @.
  7. Explain the why in half a line when a rule is counterintuitive. “Never edit schema.generated.ts: it's regenerated on every build.” A short reason keeps the rule from being worked around out of 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

  • For 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 unrequested refactoring.

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)

Poorly followed instructions 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 all of it, but nothing stands out as a priority.
  • Untestable instructions. “Write professional-quality code” produces no observable behavior.
  • The file copied from another project. It mentions 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 vs. project contradiction. Your personal file and the team's file fight over the same rule.

To check that everything is loaded, 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 badly placed or badly worded. Finally, test with a trap task: 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 prohibitions and your four commands. The rest will come on its own.