Lesson Content

CLAUDE.md is how Code mode learns about your project.

When you open Claude Code mode in a directory that contains a CLAUDE.md file, Claude reads that file before your first message. It functions as a standing brief specific to that directory and project – the equivalent of Custom Instructions, but scoped to a specific place on your computer rather than your account globally.

Everything you write in CLAUDE.md is available to Claude from the moment a Code session starts in that directory. You never need to explain the project, the conventions, the constraints, or the common commands again – they are already there.

Where CLAUDE.md files live.

A CLAUDE.md file lives in the directory it applies to. You can have:

• One in your home directory for general Code mode preferences
• One in each project directory for project-specific context
• One in a subdirectory for more specific sub-project context

Claude reads the CLAUDE.md in the current working directory and any parent directories above it (up to your home directory). This means you can have a general home-directory CLAUDE.md with your global preferences, and project-specific CLAUDE.md files that add detail for each project – and Claude will read both.

What to put in a CLAUDE.md.

An effective CLAUDE.md has four sections:

Project Overview: What this project is, what it does, and who it is for. Two to four sentences. This orients Claude immediately. Example: "This is the Dabongo LMS WordPress plugin – a custom learning management system. It imports course bundles from markdown files and manages course, lesson, and quiz data in a WordPress installation. Active development – changes deploy to a local test environment."

Tech Stack and Structure: The key technologies, frameworks, and directory organization. Lists work well here. Example: "Stack: PHP 8.1, WordPress 6.x, MySQL 8.0. Key directories: /includes (core logic), /admin (admin UI), /templates (output templates). Database: uses custom tables prefixed dabongo_."

Conventions and Rules: Naming conventions, coding standards, things Claude should always or never do in this project. Example: "Always: use snake_case for PHP variables. Use existing helper functions before writing new ones. Never: modify files in /vendor. Never: write inline SQL – use the query builder."

Common Commands: Terminal commands that Claude or you run frequently in this project. Example: "Test: cd /local/dabongo && wp plugin activate dabongo-lms. Deploy CSS: npm run build. Database reset: wp eval 'dabongo_reset_db();'"

Generating a starter CLAUDE.md with /init.

Rather than writing a CLAUDE.md from scratch, type /init in Claude Code mode while in the project directory. Claude will analyze the directory structure and generate a starter CLAUDE.md based on what it finds. This gives you a solid first draft to refine rather than a blank page. Review what /init generates carefully – it produces a good starting point but may miss context that only you know.

Keeping CLAUDE.md current.

A CLAUDE.md that is six months out of date is worse than no CLAUDE.md – it gives Claude incorrect context that you then have to correct. Treat CLAUDE.md like any project document: update it when the project changes. Add a note at the top with the last-updated date.