CLAUDE.md: teach Claude your project once

Every Claude Code session starts with a blank slate. It doesn't remember that your newsletter goes out on Thursdays, that "the shop" means your order export and not your website, or that you hate exclamation marks. So you explain it again. And again.

CLAUDE.md is where you write that down once. It's a plain text file that Claude reads at the start of every session, before you've typed a word.

What a memory file is

A CLAUDE.md file is ordinary Markdown: headings, bullets, a few lines of text. No special syntax, no settings to learn. Claude Code finds it automatically and loads it into the conversation as context.

Two things to understand up front:

• It's guidance, not a lock. Claude reads it and tries to follow it, but the docs are clear that it's context, not enforced configuration. Specific, concise instructions get followed more reliably than vague ones.
• There's a second, automatic memory. Claude Code also keeps auto memory, notes Claude writes to itself when you correct it or state a preference. You write CLAUDE.md; Claude writes auto memory. More on that at the end.

Where the files live

You can have several memory files at once, each with a different reach:

The ~ means your home folder. A project file gets shared if you share the folder (or commit it to Git). The local file is for personal notes, like your test email address; add it to .gitignore so it stays private.

Claude Code loads every CLAUDE.md it finds in the folder you started in and in each folder above it, and adds them together rather than picking one. Files in subfolders load later, when Claude starts working with files in that subfolder.

If your project already has an AGENTS.md (a similar file some other coding tools use) and no CLAUDE.md, recent versions of Claude Code read the AGENTS.md instead.

Start with /init

You don't have to write the first draft. Open Claude Code in your project and run:

/init

Claude looks through the folder and writes a starter CLAUDE.md with the commands, conventions and structure it can find. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. It also picks up instruction files from other tools, such as Cursor or Copilot rules, if you have them.

Treat the result as a first draft. Anthropic's own advice is that from here the work is "mostly removing lines."

Two commands help you check your work:

• /memory lists your memory files and opens any of them in your editor.
• /context shows what's loaded right now. Look under Memory files to confirm Claude actually sees your file.

What to put in

A good test for every line: would Claude get this wrong without being told? If it could work it out by looking at your files, leave it out.

What passes the test:

• Who it's for and how it should sound. Your audience and voice aren't in the files.
• How to check the work. The command that builds your site, the word limit for a post, the spellcheck you run. The docs call the check command "the single most useful line" in the file.
• Places that are misleading. The old-site/ folder that looks dead but isn't. The price list that's out of date.
• Decisions that aren't written anywhere else. "We never discount the course." "Invoices go out on the 1st."
• Anything you've corrected twice. The docs' own rule of thumb: if Claude makes the same mistake a second time, write it down.

What to keep out

Some things look like they belong in CLAUDE.md but work better elsewhere:

• Long procedures. "How to write the weekly newsletter, step by step" loads into every session, even the ones about your invoices. Put it in a skill, which loads only when the job comes up.
• Rules for one corner of the project. A .claude/rules/ folder holds rule files that can be limited to certain paths, so they load only when Claude works there.
• Rules that can never be broken. Since CLAUDE.md is guidance, a must-never rule ("never touch the payments folder") belongs in a permission rule or a hook, a command Claude Code runs automatically at a set moment, which enforces it every time.
• Secrets. No passwords, API keys or customer details. The project file is meant to be shared, and a key in a shared file is a leaked key.
• Personal preferences. "Call me Sam" goes in ~/.claude/CLAUDE.md or CLAUDE.local.md, not the shared file.

Keep it short

Anthropic's guidance is to keep each CLAUDE.md under 200 lines. Longer files use more of Claude's attention on every task and get followed less reliably. A few habits help:

• Write instructions you could check. "Posts are 600 to 900 words" beats "keep posts a reasonable length."
• Group by heading. Short sections with bullets are easier to follow than paragraphs.
• Hunt down contradictions. If two lines disagree, Claude may pick either one.
• Don't shout. If Claude ignores a line, writing IMPORTANT in capitals rarely fixes it. Usually the file is too long, or the rule needs to be enforced some other way.

Recent versions can audit the file for you: /doctor prompt-audit looks for outdated instructions, references to files that don't exist, and contradictions, then proposes edits without changing anything until you say so.

Imports: split it up without losing it

A CLAUDE.md can pull in other files with an @ followed by a path, like @brand/voice.md. The imported file loads alongside the main one. Paths are relative to the file doing the importing, and imports can go up to four levels deep.

Imports keep things tidy, and they let you reuse a file you already maintain, like a brand voice guide. But they don't save space: an imported file loads every session, just like the main one. If something only matters sometimes, make it a skill.

A worked example

Here's a complete CLAUDE.md for a fictional solo creator who runs a weekly newsletter, a podcast and a small course website from one folder. Swap in your own details.

# Field Notes (newsletter, podcast, course site)

## Who this is for
- Readers are freelance designers, 2 to 10 years in. Practical, busy, skeptical of hype.
- Voice: plain, warm, a little dry. Short sentences. No exclamation marks.
- Brand voice details: @brand/voice.md

## How to check work
- Newsletter issues: 600 to 900 words. Run `npm run check-links` before calling a draft done.
- Website: `npm run build` must finish with no errors.

## Where things are (only the non-obvious bits)
- issues/ holds published issues. Never edit these; they're the archive.
- drafts/ is where new issues go, named YYYY-MM-DD-slug.md.
- old-site/ looks unused but still serves the course login page. Don't delete or move it.
- pricing.md is the only source of truth for prices.

## Decisions
- We never offer discounts on the course.
- Sponsors get one line and a link, at the end, labelled "Sponsor".
- Podcast show notes link to the guest's site, never to social profiles.

## Gotchas
- Dates in this project are written 3 June 2026, not 06/03/2026.

It's about 30 lines. Notice what's missing: a description of every folder (Claude can look), generic writing advice (Claude knows it), and the step-by-step newsletter process (that's a skill).

The matching private file might hold just your own details:

- Send test emails to my own address only: sam@example.com
- I'm usually working on drafts/, so start there unless I say otherwise.

Let Claude help keep it current

You don't have to edit the file by hand every time. Ask in plain words:

add to CLAUDE.md: podcast episodes are numbered, never dated

If you say "remember that..." instead, Claude saves it to auto memory, its own notes for this project. Those live in your home folder under ~/.claude/projects/, with an index file called MEMORY.md, and the start of that index (the first 200 lines or 25KB) loads every session. Run /memory to browse what it saved, edit it, or turn auto memory off.

A good rhythm: let auto memory catch the small stuff, and once a month, read both. Promote what matters into CLAUDE.md, delete what's stale, and keep the file short enough that you'd happily read it yourself.

If you haven't set up Claude Code yet, start with your first hour.

Sources

• How Claude remembers your project, Claude Code docs
• Best practices for Claude Code, Claude Code docs
• Commands, Claude Code docs
• Extend Claude Code, Claude Code docs
• Explore the .claude directory, Claude Code docs