CC
0 XP
0

Chapter 1: Ground Zero

Understanding CLAUDE.md

concept5 min

Understanding CLAUDE.md

CLAUDE.md is the single most important file for working with Claude Code effectively. It's your project's memory.

What is CLAUDE.md?

It's a markdown file at the root of your project that Claude Code reads at the start of every session. Think of it as a briefing document — it tells Claude Code:

  • What your project is
  • How it's structured
  • What patterns to follow
  • What commands to run
  • What to avoid
💡Info

Without a CLAUDE.md, Claude Code has to figure out your project from scratch every time. With one, it picks up right where you left off.

Why CLAUDE.md works so well

Under the hood, CLAUDE.md is loaded as Claude's system prompt — the foundational context that shapes every response in a session. If you've heard of system prompts from the Anthropic API, this is the same mechanism, just saved as a file.

It also uses a technique called role prompting. When you tell Claude Code "this is a Next.js app using TypeScript and Tailwind," you're assigning it a role as a specialist in that exact stack. Research shows the more detailed the role context, the better Claude performs — just like telling a contractor exactly what kind of house you want produces better results than saying "build me a house."

A minimal CLAUDE.md

Here's what a good starting CLAUDE.md looks like:

# CLAUDE.md
 
A todo app built with Next.js 15, TypeScript, and Tailwind CSS.
 
## Commands
- `npm run dev` — Start dev server
- `npm run build` — Production build
- `npm run lint` — ESLint
 
## Stack
Next.js 15 (App Router), TypeScript, Tailwind CSS
 
## Key Locations
- `src/app/` — Pages and layouts
- `src/components/` — React components
- `src/lib/` — Utility functions

What to put in CLAUDE.md

  1. One-liner: What the project is
  2. Commands: How to build, test, and run
  3. Stack: Technologies and versions
  4. Key locations: Where important code lives
  5. Patterns: Conventions Claude should follow
  6. Constraints: Things Claude should NOT do
✅Tip

Keep CLAUDE.md concise. It's loaded into Claude Code's context window every session, so shorter is better. Aim for under 100 lines.

Let Claude write it

Here's the best part — you can ask Claude Code to write the CLAUDE.md for you:

"Read through this project and create a CLAUDE.md file with the key information you'd need to work on it efficiently."

Claude Code will analyze your codebase and generate a solid starting point. Review it, tweak it, and you're set.

CLAUDE.md grows with your project

As you build, update CLAUDE.md with new patterns, decisions, and conventions. It's a living document that makes every future session more productive.

PreviousNext