CLAUDE.md Configuration

CLAUDE.md is a special markdown file that Claude Code reads automatically at the start of every session. It acts as persistent project instructions, giving Claude the context it needs to work effectively in your codebase.

What is CLAUDE.md?

Think of CLAUDE.md as a README for your AI assistant. When Claude Code launches in a directory that contains a CLAUDE.md file, it reads the contents and treats them as baseline instructions for the entire session. This means you do not have to repeat project-specific details every time you start a conversation.

Where to Place CLAUDE.md

Claude Code checks multiple locations for instruction files, with the following priority order:

  1. Project root — ./CLAUDE.md in the repository root. This is the most common location and applies to the entire project.
  2. Home directory — ~/.claude/CLAUDE.md applies to all projects on your machine. Use this for personal preferences and global conventions.
  3. Team shared — Committed to version control so everyone on the team gets the same instructions.

When multiple files exist, Claude merges them together, with project-level instructions taking precedence.

What to Include

A good CLAUDE.md covers the essentials without overwhelming Claude with unnecessary detail. Here is an example:

# My Project

## Tech Stack
- Next.js 14 with App Router
- Tailwind CSS 4 with shadcn/ui
- Convex for database and backend
- TypeScript with strict mode enabled

## Commands
- `npm run dev` — Start dev server on port 3000
- `npm run build` — Production build
- `npm run lint` — Run ESLint

## Conventions
- Use functional components with hooks
- Prefer named exports over default exports
- Keep components in app/ directory using colocation
- Use server components by default, add "use client" only when needed

## Important Context
- The API layer is in convex/ directory
- Authentication is handled by Clerk
- All database queries go through Convex, never direct DB access

Tips for Effective CLAUDE.md Files

  • Be concise. Claude reads the entire file at session start, so keep it focused on what matters most.
  • Include commands. Listing your dev, build, and test commands saves time in every session.
  • Describe conventions. If your team follows specific patterns, spell them out so Claude follows them too.
  • Update regularly. As your project evolves, keep CLAUDE.md current so Claude always has accurate context.
  • Avoid secrets. Never put API keys, tokens, or passwords in CLAUDE.md since it is typically committed to version control.

Verifying CLAUDE.md is Loaded

You can confirm that Claude has read your CLAUDE.md by asking it directly at the start of a session. Run /status or simply ask "What do you know about this project?" and Claude will reference the instructions it loaded.