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 it knows nothing about your project or how 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 you even ask 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 coworker who already knows the place.

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 really 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 in the chat is simple: your 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 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 when 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, edit auto-generated files, install a new dependency without asking).

One thing a lot of people find out too late: every line of this file is re-read at every session and eats into 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 completely new to the tool, start with the Claude Code tutorial for beginners, 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 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 editing 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 matters most. Since it's versioned alongside 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 starting a message with the # character asks 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, which is useful for avoiding duplication of documentation you already have. The locations and 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, avoid contradicting yourself: if your personal file says “answer in English” and the project file says “answer in French,” you'll get inconsistent 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 take the same amount of time or the same starting level.

Method 1: Learn 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 perk is the built-in AI Lab: you use 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, the RS7439 in AI content marketing and the 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: The /init command in Claude Code

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: the generated file describes what it sees, not what you want. It doesn't know your hard limits, the project's gotchas, or the fact that a given folder must never be touched. Treat /init as a draft to review line by line and fill in by hand. The command is one of the 20 Claude Code commands worth knowing if you want the full picture.

Method 3: Write the file by hand

You create a file named CLAUDE.md at your project root with your editor and fill it in. This route takes the most thought, 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 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 done” works. “Ideally we should keep quality in mind” says nothing actionable.
  2. Make every rule verifiable. 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 wide 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 absolute hard limits at the top, in a short section. Three to five lines max, clearly labeled. Buried in the middle of forty recommendations, they slip through the cracks.
  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 to 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 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 type(scope): description format.
  • 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 contradicting another memory file.

The most common cases:

  • The endless 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 mentions commands that don't exist, which causes 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 are fighting over the same rule.

To check that everything is loaded, three simple moves. Type /memory to see the files 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 hard limit doesn't show up, it's badly placed or badly worded. Finally, test a trap task: ask for something that skirts a hard limit 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, add your three hard limits and your four commands. The rest will come on its own.