Writing CLAUDE.md: permanent memory for Claude Code

Every time you start Claude Code, it forgets who you are. Fresh conversation, no memory of what you discussed yesterday, no idea what your project is about or how you like things done.

Unless you leave it a note.

CLAUDE.md is a text file you put in your project folder. Claude Code reads it automatically at the start of every conversation. It's like a sticky note on the fridge: "This is the project, this is what matters, this is what NOT to do."

One file. Permanent memory. Every session starts informed instead of clueless.

I use this myself on every project I work on. My CLAUDE.md files typically include the tech stack, folder structure, coding standards, and things I want Claude to remember or avoid. This article will show you how to build your own.

What Goes in a CLAUDE.md

It's the briefing you'd give a new team member on their first day. Not everything. Just the essentials:

• What is this project?
• What technology or tools are involved?
• What's important to you?
• What should Claude avoid doing?

Write down what you want to happen, and what you want Claude to avoid. If you know something will come up repeatedly, or if there's a behavior you want to prevent, put it in the file.

A simple one for a personal website:

# My Portfolio Website

## Project
Personal website with home, about, projects, and contact pages.
Built with HTML and CSS. No JavaScript frameworks.

## Design Preferences
- Dark background (#1a1a1a), light text (#f0f0f0)
- Clean, minimal layout
- Font: Inter for everything
- No rounded corners

## Rules
- Don't delete any existing content when editing pages
- Keep all images in the images/ folder
- Every page must have a page title and meta description

That's 15 lines. Claude now knows the project, your design preferences, and your ground rules. Every session. Without you repeating yourself.

What Belongs Here (and What Doesn't)

I've learned the hard way: more isn't better. A bloated CLAUDE.md gets ignored. Claude literally stops following rules when there are too many of them.

Worth including:

• Commands that aren't obvious (your specific build script, test runner quirks)
• Style preferences that differ from conventions (you like tabs, not spaces)
• Project-specific gotchas ("the auth module has legacy code, don't refactor it")
• Folder structure decisions ("all API routes go in /api, not /routes")

Leave out:

• Things Claude can read from your code (it can see your package.json)
• Standard practices ("use meaningful variable names," Claude knows)
• Documentation that changes often (link to docs instead of copying them)

My rule of thumb: if I removed a line and Claude would still do the right thing, I remove it.

Where to Put It

Put CLAUDE.md in the root of your project folder. The root is the top-level folder, not inside a subfolder.

my-website/
  CLAUDE.md        <-- Right here
  index.html
  about.html
  css/
  images/

Claude Code automatically looks for this file when you start a conversation from this folder. You don't need to tell Claude to read it. It just does.

The file name matters: it must be CLAUDE.md (all caps CLAUDE, lowercase md). Other names won't work.

If you already have some files in your project, run /init in Claude Code. It looks at your existing code and generates a starter CLAUDE.md based on what it finds (build tools, test frameworks, folder structure). On an empty folder it won't have much to work with, so you're better off starting from one of the templates below.

Start Small

You don't need to write a novel. Five lines is a perfectly good CLAUDE.md. You can always add more later as you discover things you want Claude to remember.

It's like managing a team. You have developers, designers, and testers all in one person. Claude has all those skills, but without guidance, it'll make its own decisions about code style, folder structure, and workflows. Your CLAUDE.md is how you say "this is how we do things on this project."

I personally prefer keeping my CLAUDE.md concise. No code examples inside it, just clear rules and context. Brief statements work better than paragraphs.

Bad approach: spend an hour writing a complete document before you've even started building.

Good approach: start with the basics. When Claude does something you don't want, add a rule. When you find yourself repeating the same instruction every session, put it in CLAUDE.md.

Keep Personal Stuff Out

One important rule: don't put sensitive information in your CLAUDE.md.

• No real passwords: Not even "just for testing"
• No API keys or tokens: Use environment variables instead
• No personal secrets: Assume others might see this file

It's fine to document things like "local dev uses port 3000" or "test user login is admin/admin123" if that's a known test credential. Just don't put anything you'd be uncomfortable sharing.

For personal preferences you want to keep private, there's CLAUDE.local.md. Same format, same location, but it stays on your machine only.

Referencing Other Files

You can pull in content from other files using @:

See @README.md for project overview.
Git workflow: @docs/contributing.md

Handy when your project already has documentation and you don't want to duplicate it.

Multiple Memory Levels

Claude Code checks for CLAUDE.md in several places:

1. Your home folder (~/.claude/CLAUDE.md): Rules for all your projects
2. Project root: The main one, shared with your team
3. Subfolders: Loaded only when working in that area

Start with just the project root. That covers most needs. The global one is useful later for personal preferences that apply everywhere.

Windows location: C:\Users\YourName\.claude\CLAUDE.md
Mac/Linux location: ~/.claude/CLAUDE.md

Templates to Steal

Here are three starter templates. Copy the one closest to your situation and edit it. Each covers different aspects of what you might include.

Personal website (design-focused):

# Personal Website

Simple portfolio site with HTML and CSS.
Pages: home, about, projects, contact.

## Brand Colors
- Background: #0d0d0d (almost black)
- Text: #e8e8e8 (off-white)
- Accent: #00ff88 (bright green)
- Links: #66b3ff (soft blue)

## Rules
- Keep it simple. No JavaScript unless absolutely necessary
- All images go in images/ folder
- Don't modify files I haven't mentioned

Small business site (content-focused):

# Café Central

Website for a local coffee shop in Vienna.
Pages: home, menu, about, location, contact.
Warm brown tones, cream background.

## Important
- Business name is always "Café Central" (with accent on é)
- Phone number: +43 1 234 5678
- Address: Herrengasse 14, 1010 Wien, Austria
- Hours: Mon-Fri 7:00-18:00, Sat-Sun 8:00-16:00

File organizing project (architecture-focused):

# Photo Organization

Organizing 10 years of photos into folders by year and month.

## Folder Structure
- Source: all files in downloads/ and desktop/photos/
- Destination: organized/ with year/month subfolders
- Example: organized/2024/03/ for March 2024

## Rules
- Never delete original files. Copy, don't move
- Keep original filenames
- Skip duplicates (same filename and size)

Growing Your CLAUDE.md

My CLAUDE.md is about 150 lines. But I started with 10. It grew over months as I added things:

• Design system details (colors, fonts, spacing values)
• Build process commands
• Folder structure explanations
• Rules about what not to change
• Style guidelines for content

Every time Claude did something I didn't want, I added a line to prevent it next time. Every time I found myself repeating an instruction, I moved it to CLAUDE.md.

Your CLAUDE.md will grow the same way. Organically. Based on real problems, not hypothetical ones.

One tip: it's perfectly fine to use Claude itself to help you improve your CLAUDE.md. I sometimes paste mine into Claude.ai and ask for suggestions on what's unclear or could be better organized. Fresh eyes, even AI ones, help.

Scaling Up

When your project grows and a single CLAUDE.md gets messy, you can split instructions into separate files in a .claude/rules/ folder:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

Every .md file in .claude/rules/ is automatically loaded as project memory, with the same priority as your main CLAUDE.md. No configuration needed. Just create the files and Claude picks them up.

One topic per file

The whole point of splitting is focus. Each file should cover exactly one topic. Instead of a 200-line CLAUDE.md with everything jumbled together, you get clean, scannable files that are easy to update.

Good filenames tell you what's inside: testing.md, api-design.md, database.md. If you find yourself writing misc.md or other-rules.md, you probably haven't split things enough.

Path-specific rules

This is where it gets interesting. You can scope rules to specific files using YAML frontmatter at the top of a rule file:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

These conditional rules only kick in when Claude works with files matching the specified patterns. Rules without a paths field load unconditionally and apply everywhere.

The paths field supports standard glob patterns:

You can also combine multiple patterns and use brace expansion:

paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"

Use this sparingly though. Most rules apply project-wide. Only add paths when rules actually apply to specific file types or directories.

Organizing with subdirectories

For bigger projects, group related rules into folders:

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

All .md files are discovered recursively, so subdirectories work without any extra setup.

Tips for rule files

• Keep each file focused. One topic per file. If a file covers two unrelated things, split it.
• Use descriptive filenames. The name should tell you what's inside without opening it.
• Don't over-split. Three lines of testing rules can stay in CLAUDE.md. Split when a topic actually grows large enough to justify its own file.
• Project rules take priority. If you have personal rules in ~/.claude/rules/, project-level rules in .claude/rules/ override them when they conflict.

For the complete reference on modular rules, see the official documentation on memory and rules.

Handy Commands

• /init: Generate a starter CLAUDE.md (works best on existing projects with some files)
• /memory: Open your memory files for editing

Learn More

For the complete reference on memory files, see the official Claude Code documentation.

Next up: saving your best prompts as reusable commands. Type a short name instead of a paragraph.