A CLAUDE.md file gives Claude Code persistent knowledge about your project, acting as its "memory" for your codebase's unique setup and rules.

📁 Creating Your CLAUDE.md File

You have two main options to create this file:

Method Process Best For

Automatic (/init) In your project's root directory, run claude, then type /init. Claude scans your project and generates a starter file. Quickly bootstrapping a new project or when you're unsure what to include.

Manual Create a new markdown file named CLAUDE.md (case-sensitive) in your project's root. Start with a basic project overview. Full control from the start or for simple projects.

Whether you generate or create the file manually, treat it as a living document that you edit and refine over time.

🗺️ How to Use It Effectively

Think of CLAUDE.md as an onboarding guide for Claude. To make it effective:

Start Small and Build: Begin with just the essentials: a one-line project description, key terminal commands (npm run dev, docker-compose up), and critical "gotchas" (e.g., "NEVER commit .env files"). Add rules only when Claude makes a consistent mistake.

Structure for Clarity: Use clear Markdown headings. Common sections include:

Project Overview

Common Commands

Code Style

Important Notes / Gotchas

Place It Strategically: You can have multiple CLAUDE.md files in a hierarchy:

Project Root: The standard location for project-wide rules.

Subdirectories: For monorepos, place files in subfolders (e.g., /api/CLAUDE.md) for module-specific rules.

Home Directory (~/.claude/): For your personal, global preferences across all projects.