Two CLAUDE.md Files

The core concept of Claude Code Setup: two Markdown files that serve as persistent memory.

Overview

File	Location	Purpose
Global	`~/.claude/CLAUDE.md`	Your workflow, conventions, preferences
Project	`your-project/CLAUDE.md`	Current status, tasks, next steps

Both files load automatically when you start Claude Code.

Global CLAUDE.md

Located at ~/.claude/CLAUDE.md, this file contains:

Workflow instructions - How to use /catchup, /wrapup, etc.
Conventions - Commit message format, code style preferences
Skill loading rules - When to load which coding standards
User Instructions - Your personal customizations (preserved during updates)

This file applies to all projects.

Project CLAUDE.md

Located in your project root, this file contains:

Project overview - Name, description, tech stack
Current Status - Active tasks with status and notes
Recent Decisions - Small decisions that survive /clear
Project Instructions - Project-specific preferences (preserved during migrations)
Architecture - High-level patterns and component interactions
Files - Project structure overview
Development commands - Project-specific commands

This file is project-specific.

How They Work Together

~/.claude/CLAUDE.md          your-project/CLAUDE.md
┌─────────────────────┐      ┌─────────────────────┐
│ Workflow rules      │      │ Project: MyApp      │
│ Conventions         │  +   │ Status: Auth done   │
│ Skill loading       │      │ Next: Add logout    │
│ User preferences    │      │ Project prefs       │
└─────────────────────┘      └─────────────────────┘
           │                          │
           └──────────┬───────────────┘
                      ▼
              Claude knows:
              - HOW to work (global)
              - WHAT to work on (project)

Preserved Sections

Both CLAUDE.md files have sections with markers that survive updates and migrations.

User Instructions (Global)

<!-- USER INSTRUCTIONS START -->
Your personal preferences here.
<!-- USER INSTRUCTIONS END -->

For personal customizations: language preferences, conventions, tool preferences, credential locations.

Project Instructions (Project)

<!-- PROJECT INSTRUCTIONS START -->
Project-specific preferences here.
<!-- PROJECT INSTRUCTIONS END -->

For project-specific rules: testing conventions, deployment preferences, coding rules shared with the team.

/init-project - Creates project CLAUDE.md
Workflow - How the files are used

First Session Records