1.4: Project Memory (CLAUDE.md)

The Problem

Every time you start a new Claude Code session, you lose context. You have to re-explain your project, your preferences, your terminology. This gets tedious fast.

The Solution: CLAUDE.md

CLAUDE.md is a special file that Claude reads automatically at the start of every session. Think of it as a constitution for your project—rules and context that persist across conversations.

How It Works

1. Create a file called CLAUDE.md in your project root
2. Write your project context and rules
3. Claude reads it automatically—no action needed from you

my-project/
├── CLAUDE.md          ← Claude reads this first
├── docs/
├── src/
└── README.md

What to Include

Project Overview

# Project: Customer Dashboard

This is an internal tool for our sales team to track customer health scores.
The primary users are account managers who are not technical.

User Personas

## Users

- **Sarah** (Account Manager): Needs quick access to customer health metrics.
  Doesn't understand technical jargon. Values simplicity over features.

- **Mike** (Sales Director): Wants high-level reports for leadership meetings.
  Cares about trends, not individual data points.

Writing Style

## Voice and Tone

- Professional but friendly
- Avoid jargon; explain technical terms if necessary
- Use active voice
- Keep sentences short

Terminology Rules

## Terminology

- ALWAYS say "customer" not "client"
- ALWAYS say "health score" not "rating"
- NEVER abbreviate "customer" as "cust"

Immutable Rules

## Rules

- Never delete files without explicit confirmation
- Always create backups before major edits
- Use ISO date format (YYYY-MM-DD) everywhere

What NOT to Include

CLAUDE.md Hierarchy

CLAUDE.md can exist at multiple levels. More specific locations take precedence:

Writing Effective Rules

Be specific

# Bad
Write good code

# Good
Use descriptive variable names of 3+ words. Avoid single-letter variables except for loop indices.

Explain the “why”

# Good
Always use "customer" not "client" (our brand guidelines require this for consistency)

Use imperative language

# Good
ALWAYS include error handling in API calls
NEVER commit directly to main branch

# Less effective
It would be nice to have error handling

Best Practices

• Keep it scannable with bullet points and headers
• Review quarterly as your project evolves
• Aim for 50-200 lines—enough context without overwhelming
• Version control it so the whole team shares context

Quick Start Template

# Project: [Name]

[One paragraph describing what this project is]

## Users

- **[Persona 1]**: [Description and needs]
- **[Persona 2]**: [Description and needs]

## Voice

- [Style guideline 1]
- [Style guideline 2]

## Rules

- ALWAYS [rule]
- NEVER [rule]

Ready to create your CLAUDE.md? Run start 1-4 for a guided setup.