Step 1: Project CLAUDE.md
Lives at your repo root. Shared by the whole team. Contains project specific conventions, commands, and architecture notes.
Step 2: Project settings
The .claude/settings.json file stores machine readable config: permissions, MCP servers, environment variables.
Step 3: User CLAUDE.md
Personal instructions at ~/.claude/CLAUDE.md. Applies to every project. Your global preferences and style rules.
Step 4: Auto Memory
Persistent memory at .claude/memory/ that records patterns, decisions, and insights across sessions automatically.
| Layer | Location | Scope | Use Case | |
|---|---|---|---|---|
| Project CLAUDE.md | CLAUDE.md | Repo root | All team members | Conventions, commands, architecture |
| Project settings | .claude/settings.json | Repo root | All team members | Permissions, MCP servers |
| User CLAUDE.md | ~/.claude/CLAUDE.md | Home directory | You only | Personal preferences, global rules |
| Auto memory | .claude/memory/ | Per project | You only | Learned patterns, debugging notes |
| Rules directory | .claude/rules/ | Per project | All team members | Individual versioned rules |
Getting started with CLAUDE.md
Run
/init as your first step in any new project. It analyzes your repo and generates a solid CLAUDE.md automatically. Then review it, remove anything incorrect, and add your team's specific conventions. A good CLAUDE.md is the single biggest productivity improvement you can make with Claude Code.What a good CLAUDE.md looks like
A well written CLAUDE.md covers the essentials your team needs Claude Code to know. Here is a simplified example:
# My Project
## Overview
React 19 + TypeScript + Supabase SaaS app.
## Commands
- `npm run dev` — Start dev server
- `npm run build` — Production build
- `npm test` — Run tests with Vitest
## Conventions
- Use functional components with hooks
- Prefer server components for data fetching
- All API calls go through lib/api/
- Use Tailwind for styling, no CSS modules
## Gotchas
- crypto.randomUUID() crashes on mobile over HTTP
- Always run prettier before committingHow auto memory differs from CLAUDE.md
CLAUDE.md is explicit: you write the rules and instructions deliberately. Auto memory is implicit: Claude Code learns from your interactions and records patterns automatically. CLAUDE.md is shared with your team via version control. Auto memory is personal and stays on your machine. Both are loaded at the start of every session. Use CLAUDE.md for team standards and auto memory for your personal workflow preferences.