AI
November 18, 2026
6 min read

How to Write a Good CLAUDE.md for Claude Code

CLAUDE.md is your contract with Claude Code. Learn what to put in it, the four levels, @ imports, conditional rules and the commands that help.

The CLAUDE.md file is a Markdown file that Claude Code loads at the start of every session. Think of it as a contract between you and Claude: what it must know about your project so it does not make mistakes. Here is how to write one well.

The core principle: write what the code does not say

There is no point describing the folder layout or the list of dependencies in CLAUDE.md. Claude can see those on its own. Write only what cannot be inferred from the code.

The test for every line is simple: would Claude make a mistake without it? If not, delete it. Every line in the file costs tokens on every turn of the conversation.

Four levels of CLAUDE.md

There are several places to put the file. They add up; they do not override each other:

LevelLocationWho sees it
ManagedOrganization policy (managed by IT)The whole organization
User~/.claude/CLAUDE.mdOnly you, in all projects, on this machine only
Project./CLAUDE.md or ./.claude/CLAUDE.mdThe whole team (committed to git)
Local./CLAUDE.local.mdOnly you, in this project (gitignored)

All levels are joined into a single prompt. Claude walks up the directory tree and loads every CLAUDE.md it finds. Files in subfolders are loaded only when you work on them.

A recommended structure: under 200 lines

Here is a skeleton to start from:

# Project name
One or two sentences: what it is and who it is for.

## Stack
Only the unexpected parts (for example: "Postgres 17 with RLS, not Prisma").

## Conventions
What you would comment on in a Code Review.

## Always
- Run `pnpm test` before finishing.

## Never
- Do not edit `migrations/` by hand.

## Gotchas
- `config.ts` is loaded twice in dev. This is intentional.

According to the guide, the "Never" section is the most valuable one, because it comes from real failures. Every time Claude does something you did not want, that is a chance to add one line there.

Importing files with @

When information is too long for the body of the file, you can import another file:

@docs/architecture.md
@~/.claude/my-preferences.md
  • @path/to/file is expanded in full at startup.
  • You can nest imports up to 4 levels deep.
  • Imports survive /compact: they are reloaded after compaction.

Conditional rules with .claude/rules/

An @ import is always loaded. If a rule matters only for part of the codebase, put it in .claude/rules/ with paths: in the file header:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Every endpoint returns `{ data, error }`.

The rule loads only when Claude touches files that match the pattern. From version 2.1.285, such rules also load on Write and Edit, not only on reads.

Commands that help

  • /init: creates a first CLAUDE.md. It tends to describe what is already visible in the code, so edit and delete without mercy. Setting CLAUDE_CODE_NEW_INIT=1 enables an interactive version that also goes over Skills and Hooks.
  • /memory: opens your CLAUDE.md files for editing.
  • /doctor prompt-audit (new in 2.1.283): checks your CLAUDE.md, Skills and Agents and flags outdated prompting patterns. Worth running after every model upgrade.
  • /import codex|gemini|cursor: brings instruction files, MCP and commands over from Codex, Gemini CLI or Cursor.

A short checklist before you finish

  1. The file is under 200 lines.
  2. Every line passes the test: Claude would make a mistake without it.
  3. There is a "Never" section born from real mistakes.
  4. Rules that apply to only part of the code moved to .claude/rules/ with paths:.
  5. Personal preferences live in User or Local, not in Project, which the whole team sees.

You can also ask Claude to explain code you inherited: the gaps it reveals are new lines for your CLAUDE.md.

Quick start in four steps

According to the guide, this is a reasonable start in a new project. Inside the session:

  1. /init: creates an initial CLAUDE.md. Edit it and keep only what the code does not say.
  2. /context: see what is actually loaded into the context window.
  3. Shift+Tab: switches between permission modes (the default is now auto).
  4. For a change across several files, start with /plan.

Example: a line worth keeping versus a line worth deleting

A line like "The project is written in TypeScript and has a src folder" is something Claude sees on its own, so you can delete it. A line like "Postgres 17 with RLS, not Prisma" is exactly the kind that prevents a mistake, because nobody can assume it in advance. The same goes for "do not edit migrations/ by hand": it is an instruction born from a failure, and it is worth the tokens.

Two items from the guide's "ten things to do this week" list apply directly here: trim CLAUDE.md to under 200 lines, and move conditional rules to .claude/rules/ with paths:.

It also helps to remember that the file is a living document. It is not written once and forgotten: every repeated failure of Claude is a sign of a missing line, and every line that no longer prevents mistakes is a candidate for deletion. A periodic check with /doctor prompt-audit, especially after a model upgrade, helps catch outdated instructions.

The full guide is free on GitHub (in Hebrew), and also available as a website: https://tovtechorg.github.io/Claude-Code-in-Hebrew/.