If you keep explaining the same project rules to Claude Code over and over, write them down in CLAUDE.md. It's an ordinary text file in Markdown, nothing fancier than that. Claude Code reads it at the start of a session and picks up your conventions along with the rest of the context.

A few proven lines are enough to start with: where to work, how to check the result, and what has to survive any changes.

A CLAUDE.md example

Take a simple page with cards. The markup, the styles, and the JavaScript all live in a single index.html, and you can open the page right in the browser. For a project like that, the instructions file might look like this:

# CLAUDE.md

## Project
- The page, the styles, and the JavaScript are all in `index.html`.

## Checking
- Open `index.html` in a browser.
- Check the page on a wide and a narrow screen.

## Rules
- Keep the current colors and card styling.
- Don't delete finished blocks without confirmation.
- When you're done, list the changes and the checks.

Three groups here: how the project is put together, how to check the result, and what you've agreed on. Now a request like "add one more card" doesn't have to list all the rules again. You can still check the page yourself. having the instruction doesn't give the agent access to a browser if it has no such tool.

This is an example for a single file, not a universal template. Your project may have separate folders and its own commands for running things. Write those down; if there are no tests, don't add a made-up command just for completeness.

C++

What's worth writing down

The main filter: will you need this note in future tasks? Proven commands, important paths, and conventions the agent can't reliably work out from the code are all useful. Especially the ones you've already had to repeat.

Phrase a rule so the expected action is obvious. Compare:

  • "check everything" → "after changing the cards, check the page on a wide and a narrow screen";
  • "don't touch anything important" → "don't delete finished blocks without confirmation: their content has already been agreed on".

The first one names the check; the second one names the boundary and the reason behind it. That beats a long list of wishes along the lines of "work carefully."

README.md explains to a person what the project is and how to get started. CLAUDE.md collects the instructions for the agent. No need to repeat the whole README. And a hunch like "the caption looks like it's shifting because of the card width" belongs in a note for the current task, say PROJECT_NOTE.md. That's a plain file with a name you pick yourself; when you come back to the task, ask the agent to read it.

Don't write down a guess as an established fact, and don't keep passwords or access keys here. A shared CLAUDE.md usually goes into Git so your teammates get the same instructions along with the project.

How to create the file and check it

Start with the rules you already know. There's no need to wait for a long list of mistakes to pile up, or to describe every possible situation in advance.

  1. Check whether the project already has a CLAUDE.md. If it does, read it and add to it. For a new file, pick the project root; the .claude/CLAUDE.md location works too, but there's no point in creating both copies.
  2. Write a few lines by hand, or type /init in a Claude Code session started in the project folder. The command will look the project over and put together a draft; for an existing file it will suggest improvements.
  3. Read the result. Check the commands and paths against the project, and delete the guesses. If the agent wrote in a test command you don't have, for instance, take it out. Any constraints only you know about, you'll have to add yourself.
  4. Save the file and open a new session in the project folder. Type /context: the Memory files section should show the path to your CLAUDE.md.

Then try a small change: ask for a card to be added, say, and see whether the colors held and whether a report on the checks showed up. If the file isn't in the list, start by checking its name and the folder you launched from. It's there, but the result doesn't match the rule? Then look at the wording and at any contradictions.

Loaded isn't the same as followed

The file showing up in the list confirms it was loaded, but it doesn't guarantee the rules will be followed. A correct answer from the agent doesn't prove the file was loaded either: the information could have come from other files. An instruction steers the work, but it doesn't put a technical block on an action.

Where the rest of it goes

For a first project one CLAUDE.md is plenty. Once personal rules show up, or a lot of shared ones do, this diagram will help you pick where a note belongs:

Where instructions and notes belongA note that only matters for the current task stays in the task note. A lasting personal rule for the project goes to CLAUDE.local.md, a shared rule to CLAUDE.md. As things grow, some shared rules can move out to .claude/rules/. Auto memory is shown separately: those are notes that Claude saves.Will you need this notein future tasks?Note forthe current taskPersonal rulefor this project?CLAUDE.local.mdCLAUDE.mdSome shared rules.claude/rules/Auto memoryNotes that Claude saves itselfNoYesYesNoIf there are many rulesor you need path scopingA separate mechanism
First decide what the note is for, then pick the file.

A shared rule can cover just one folder and still be something the whole team needs. .claude/rules/ helps you split instructions like that by topic; scoping them to specific paths is configured separately. For a couple of rules there's no reason to complicate the structure.

CLAUDE.local.md is the place for personal rules within this project, a preference for short answers, say. Add it to .gitignore so it doesn't get committed. The agent still reads the local file, so no secrets there either.

Java university

Auto memory is a separate set of notes that Claude saves as it works, if the mechanism is turned on. Don't leave an important rule entirely up to its judgment: ask outright for it to be added to CLAUDE.md. A temporary hunch about a bug stays in the task note.

If the project already has an AGENTS.md, don't copy its contents into a second file. In CLAUDE.md you can pull in a neighboring file with the line @AGENTS.md. That's especially handy when you add a CLAUDE.local.md: the personal file can affect whether AGENTS.md is read directly. Other options are described in the documentation.

When to update the rules

Edit the file as the project changes. Moved the styles out of index.html into a separate file - fix the line about the structure. Changed how you check the result - replace the old instruction. Don't pile a new rule on top of an old one that contradicts it.

A correction you keep making can be handed to the agent: "Add to CLAUDE.md that deleting a finished block needs my confirmation first." Then read the change. It should capture what you agreed on without new constraints the agent added on its own. One line is often enough, honestly.

If a rule gets broken, work out why instead of repeating it three more times. Clear out stale notes and keep only what helps with the next task.