Project Memory (CLAUDE.md)

CLAUDE.md is how Claude remembers your project across sessions. It is the single most impactful configuration you can set up—and it takes less than five minutes.

What is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code reads at the start of every session. It provides persistent context—information that Claude should always know when working on your project. Without it, Claude starts every conversation with a blank slate and needs to rediscover your project's conventions, tech stack, and preferences each time.

Think of it like onboarding documentation for a new team member. Except this team member reads it perfectly every time, never forgets, and applies it consistently to every task.

Why It Matters

Without CLAUDE.md, you end up repeating yourself constantly:

# Session 1
> We use Tailwind CSS, not styled-components
> Our API routes go in src/app/api/
> We use Vitest, not Jest

# Session 2 (Claude has forgotten everything)
> Remember, we use Tailwind CSS...
> The API routes are in src/app/api/...
> Use Vitest for tests...

With CLAUDE.md, Claude knows all of this before you even start typing. Every session feels like working with a colleague who already understands the project.

Creating Your First CLAUDE.md

The easiest way to create a CLAUDE.md is with the /init command. Claude will analyze your project and generate a starter file.

$ cd ~/Projects/my-project

$ claude
> /init

$ git add CLAUDE.md
$ git commit -m "Add project memory for Claude Code"

What to Put in CLAUDE.md

The most effective CLAUDE.md files cover these areas. You do not need all of them—start with what matters most for your project and add more over time.

Project Overview

A brief description of what the project does, who it is for, and its current state.

# Project: InvoiceApp

A SaaS invoicing tool for freelancers. Currently in beta with
~500 active users. The frontend is a Next.js 14 app, and the
backend uses Supabase for auth, database, and storage.

Tech Stack and Dependencies

## Tech Stack
- **Framework:** Next.js 14 (App Router)
- **Language:** TypeScript (strict mode)
- **Styling:** Tailwind CSS + shadcn/ui components
- **Database:** Supabase (PostgreSQL)
- **Auth:** Supabase Auth with Google OAuth
- **Payments:** Stripe
- **Testing:** Vitest + Playwright for E2E
- **Deployment:** Vercel

Coding Conventions

This is the highest-impact section. Tell Claude how you want code written.

## Coding Conventions
- Use functional components with hooks (no class components)
- Name components in PascalCase, utilities in camelCase
- All components go in src/components/ with a folder per component
- Use "use server" and "use client" directives explicitly
- Prefer named exports over default exports
- Error handling: always use try/catch with typed error boundaries
- No console.log in production code — use our logger utility
- All API responses follow the { data, error } pattern

Build and Test Commands

## Commands
- `npm run dev` — Start the dev server on port 3000
- `npm run build` — Production build
- `npm run test` — Run Vitest unit tests
- `npm run test:e2e` — Run Playwright E2E tests
- `npm run lint` — ESLint + Prettier check
- `npm run db:migrate` — Run Supabase migrations

Project Structure Notes

## Project Structure
- src/app/ — Next.js App Router pages and layouts
- src/components/ — Reusable UI components
- src/lib/ — Utility functions and shared logic
- src/hooks/ — Custom React hooks
- src/types/ — TypeScript type definitions
- supabase/migrations/ — Database migrations
- tests/ — E2E and integration tests

Things to Avoid

Explicitly telling Claude what not to do is just as valuable as telling it what to do.

## Do NOT
- Do not install new packages without asking me first
- Do not modify the database schema directly — use migrations
- Do not use any AI-generated placeholder comments like "// rest of code here"
- Do not create new files in the root directory
- Do not use relative imports — always use the @/ alias

The CLAUDE.md Hierarchy

Claude Code supports multiple CLAUDE.md files at different levels. They are read in order, with more specific files taking precedence.

Global (User-level)

Located at ~/.claude/CLAUDE.md, this file applies to every Claude Code session regardless of project. Use it for personal preferences that never change.

# ~/.claude/CLAUDE.md (Global)

## Personal Preferences
- I prefer TypeScript over JavaScript
- Use 2-space indentation
- I like concise commit messages
- When explaining code, keep it brief — I'm an experienced developer

Project-level

Located at the root of your project directory (./CLAUDE.md). This is the most commonly used level. It contains project-specific conventions that every team member should follow. Commit this file to your repository.

Folder-level

You can place a CLAUDE.md inside any subdirectory. Claude reads it when working on files in that directory. This is useful for large monorepos or projects with distinct sections.

my-monorepo/
├── CLAUDE.md               # Shared conventions
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md       # React/Next.js conventions
│   ├── backend/
│   │   └── CLAUDE.md       # Express/Node conventions
│   └── shared/
│       └── CLAUDE.md       # Shared library conventions

Precedence Order

All CLAUDE.md files are combined, with more specific levels adding to (and overriding) more general ones:

• Global (~/.claude/CLAUDE.md) — base layer, personal preferences
• Project (./CLAUDE.md) — project-wide conventions
• Folder (./src/CLAUDE.md) — section-specific overrides

Real Example: Setting Up CLAUDE.md for a Marketing Team

You do not need to be a developer to benefit from CLAUDE.md. Here is how a marketing team might set up project memory for a website content project.

# Marketing Website — CLAUDE.md

## About This Project
Company marketing website built with Next.js. Content is managed
through MDX files in the content/ directory. The marketing team
updates content; engineering handles infrastructure.

## Brand Voice
- Professional but approachable. Never stuffy or corporate.
- Use active voice. Short sentences. Clear and direct.
- Our audience: startup founders and product managers.
- Avoid jargon unless it's industry-standard.
- Never use: "leverage," "synergy," "paradigm," "revolutionary"

## Content Structure
- Blog posts go in content/blog/ as .mdx files
- Case studies go in content/case-studies/
- Landing pages are React components in src/app/(marketing)/

## SEO Guidelines
- Every page needs a meta title (max 60 chars) and description (max 155 chars)
- Blog posts need: title, date, author, category, tags
- Use descriptive alt text on all images
- Internal links should use relative paths

## Image Guidelines
- All images in public/images/ organized by section
- Maximum width: 1200px, format: WebP preferred
- Always include alt text for accessibility

## When Creating Content
- Match the tone of existing posts in content/blog/
- Include at least one CTA per page
- Link to related content when relevant
- Front matter must include all required fields

With this CLAUDE.md, a marketing team member can ask Claude to write a blog post and it will automatically follow the brand voice, use the correct file format, include proper front matter, and place the file in the right directory.

Evolving Your CLAUDE.md Over Time

Your CLAUDE.md is a living document. The best approach is to start simple and add to it as you discover patterns.

• Start with /init and add two or three personal preferences.
• When you correct Claude, add that correction to CLAUDE.md so you never have to repeat it.
• When you notice patterns—"I always tell Claude to use Tailwind"—add them to CLAUDE.md.
• Periodically ask Claude: "Based on our conversations, what should I add to CLAUDE.md?" Claude can suggest additions based on corrections you have made.

Common Mistakes to Avoid

• Making it too long: Claude reads the entire file every session. Keep it focused and avoid duplicating information that Claude can infer from your code.
• Including secrets: Never put API keys, passwords, or credentials in CLAUDE.md. It should be committed to your repository.
• Being too vague: "Write good code" is not helpful. "Use early returns instead of nested if-else blocks" is specific and actionable.
• Not updating it: An outdated CLAUDE.md is worse than none at all if it gives Claude incorrect instructions.
• Duplicating README: CLAUDE.md is for Claude-specific instructions, not a copy of your README. Reference the README instead: "See README.md for setup instructions."