Write a CLAUDE.md that Claude Code actually loads

CLAUDE.md is the file of standing instructions Claude Code reads before anything else in a session: how you like to work, how the project is built, what never to do. A good one saves you repeating yourself. A bad one costs tokens on every message and changes nothing. This lesson writes one in Config Studio for Claude Code and checks what actually loads.

#Pick whose instructions they are

Open Memory (CLAUDE.md). The first choice, Who this applies to, decides which file you write:

Where it lives also lists the .claude/rules/ folder and AGENTS.md, which Claude Code can read too.

These files do not replace each other. They all load, together, and stay in the context for the whole session.

#Write short, specific instructions

The editor starts with an example:

# How I work

- Ask before adding a dependency.
- Match the surrounding code rather than your own style.
- When a test fails, say so with the output. Do not describe it as passing.

Notice what these have in common: each is a concrete behaviour you can check. "Write clean code" is not; Claude already tries. The file is added to every session, so every line costs tokens every time. Short and specific beats long and general.

Good things to put in a project's CLAUDE.md:

• How to build, test and lint, with the exact commands
• Where things live, when the layout is not obvious
• Conventions that differ from the usual (naming, error handling, commit messages)
• What never to touch: generated files, vendored code, migrations

#Split it with @ imports

A line with @ and a path pulls another file in at that point:

Be brief.
@./house-style.md

This keeps one instruction file readable while it grows, and lets several projects share a style guide. The catch: if the imported file does not exist, the import silently brings in nothing.

#Check what actually loads

Open Try it and pick What actually loads? Paste your user file, the project file, and the list of files that exist. The answer shows every instruction file in the order it loads (managed, user, project, local), what each @ import brings in, and which imports point at files that are not there.

It is the fastest way to find out why an instruction is being ignored: often it was never loaded.

#Check the instructions say what you mean

Is the habit in the prompt, or only in your head? reads a prompt, an instructions file or a command, and checks six things it either has or does not:

• It says what to do
• Instructions and data are separated
• It shows an example
• It says what the answer should look like
• No vague word is doing the work of a number
• It says what not to do, or where to stop

It does not judge whether the prompt works. It shows what you left for the model to guess.

#Take it away

The file on the right is your CLAUDE.md. As soon as you set anything on the surface, Memory (CLAUDE.md) is ticked in the Surfaces list, so it is in your plan; untick it to leave it out. The file is marked appends: for a CLAUDE.md that already exists, the install adds your text to it instead of replacing it.

The next lesson adds your own scripts to Claude Code's life cycle: hooks.