CLAUDE.md Files: Teaching Claude About Your Project
Every project has conventions that are not obvious from the code alone. Maybe you use a specific naming pattern, prefer a particular testing approach, or have architectural rules that are not enforced by a linter. CLAUDE.md files let you communicate all of this to Claude Code so it follows your project's rules automatically.
In this lesson, you will learn how to create and organize CLAUDE.md files to make Claude Code a true expert on your project.
What You Will Learn
- What CLAUDE.md files are and how Claude Code uses them
- Where to place CLAUDE.md files in your project
- What to include in your CLAUDE.md for maximum effectiveness
- How to structure instructions for different scopes
- The hierarchy of CLAUDE.md files (project, directory, user)
- Real-world examples from production projects
What Is a CLAUDE.md File?
A CLAUDE.md file is a Markdown file that gives Claude Code project-specific instructions. Think of it as a README, but written specifically for your AI coding assistant. When Claude Code starts a session, it automatically reads all relevant CLAUDE.md files and follows the instructions within them.
Without a CLAUDE.md, Claude Code still works well by analyzing your code. But with one, it works like a team member who has read your style guide, attended your architecture meetings, and understands your team's preferences.
Where CLAUDE.md Files Live
Claude Code looks for CLAUDE.md files in several locations, each with a different scope:
Project Root CLAUDE.md
The most important one. Place it at the root of your repository:
my-project/
CLAUDE.md <-- Project-wide instructions
src/
package.json
This file is loaded for every conversation in the project. Use it for project-wide conventions, architecture decisions, and build commands.
Directory-Level CLAUDE.md
You can place CLAUDE.md files in subdirectories for scoped instructions:
my-project/
CLAUDE.md <-- Project-wide
src/
api/
CLAUDE.md <-- Instructions specific to API code
frontend/
CLAUDE.md <-- Instructions specific to frontend code
Directory-level CLAUDE.md files are loaded when Claude Code works with files in that directory. This is useful for monorepos or projects with distinct sections.
User-Level CLAUDE.md
Your personal preferences live in ~/.claude/CLAUDE.md. These apply to every project:
~/.claude/CLAUDE.md <-- Your personal preferences
Use this for personal preferences like your preferred code style or communication style with Claude Code.
The Hierarchy
When multiple CLAUDE.md files apply, Claude Code reads all of them. The priority order from most to least specific is:
- Directory-level CLAUDE.md (most specific)
- Project root CLAUDE.md
- User-level ~/.claude/CLAUDE.md (most general)
More specific instructions take priority when there is a conflict.
What to Include in Your CLAUDE.md
Build and Development Commands
Start with the commands Claude Code needs to know:
## Build Commands
- `npm run dev` - Start development server
- `npm run build` - Production build
- `npm test` - Run all tests
- `npm run lint` - Lint code
- `npm run typecheck` - TypeScript type checking
## Single Test File
Run individual tests with:
npm test -- path/to/test.ts
This ensures Claude Code runs the right commands for your project instead of guessing.
Architecture and Structure
Explain your project's architecture so Claude Code understands the big picture:
## Architecture
This is a Next.js 16 app with App Router:
- `src/app/` - Routes and pages
- `src/components/` - Reusable React components
- `src/lib/` - Business logic and utilities
- `src/types/` - TypeScript type definitions
We use Supabase for the database and auth.
Path alias: `@/*` maps to `./src/*`.
Coding Conventions
Document your team's conventions:
## Coding Conventions
- Use named exports, not default exports
- Use `interface` for object types, not `type`
- All React components must be functional components with arrow syntax
- Use `const` by default, `let` only when reassignment is needed
- Error messages should be user-friendly, not technical
- All API responses follow the format: \{ success: boolean, data?: T, error?: string \}
Testing Conventions
Explain how your team writes tests:
## Testing
- Use Jest with React Testing Library
- Test files live next to source files: `Component.tsx` and `Component.test.tsx`
- Mock external services, not internal modules
- Every new API endpoint must have integration tests
- Use `describe` blocks for grouping related tests
- Test names should describe behavior: "should return 404 when user not found"
Things to Avoid
Explicitly state what Claude Code should NOT do:
## Important: Do NOT
- Do not use `any` type in TypeScript
- Do not use `console.log` for error handling (use the logger utility)
- Do not modify files in `src/generated/` (these are auto-generated)
- Do not use relative imports that go up more than one level (use @/ alias)
- Do not add new dependencies without mentioning it first
Real-World CLAUDE.md Examples
Example 1: Full-Stack Web App
# CLAUDE.md
## Project Overview
E-commerce platform built with Next.js 16, Prisma, and PostgreSQL.
## Commands
- `npm run dev` - Dev server on port 3000
- `npm run build` - Production build
- `npm test` - Jest tests
- `npx prisma migrate dev` - Run database migrations
- `npx prisma generate` - Regenerate Prisma client
## Architecture
- App Router in src/app/
- Server Actions in src/app/actions/
- Database models in prisma/schema.prisma
- Shared types auto-generated from Prisma
## Conventions
- All database queries go through Prisma, never raw SQL
- Server Actions handle form submissions
- Use Zod for all input validation
- Prices are stored in cents (integers), formatted for display
- All dates are stored in UTC
## Do NOT
- Never expose Prisma models directly to the client
- Never skip input validation on API routes
- Never use client-side state for data that should be server-side
Example 2: Monorepo
# CLAUDE.md
## Monorepo Structure
This is a Turborepo with multiple apps and packages:
- `apps/web` - Main web application (Next.js)
- `apps/api` - REST API (Express)
- `apps/mobile` - Mobile app (React Native)
- `packages/shared` - Shared types and utilities
- `packages/ui` - Shared UI components
## Commands (run from root)
- `npm run dev` - Start all apps
- `npx turbo dev --filter=web` - Start only the web app
- `npx turbo test --filter=shared` - Test only shared package
- `npm run build` - Build everything
## Cross-Package Rules
- Shared types must go in `packages/shared`
- UI components must go in `packages/ui`
- Apps can import from packages but never from other apps
- All packages must have a consistent tsconfig that extends the root
Tips for Effective CLAUDE.md Files
Keep it concise. Claude Code reads the entire CLAUDE.md at the start of every conversation. Long files waste context space. Focus on information that is not obvious from the code itself.
Update it regularly. As your project evolves, update the CLAUDE.md to reflect current conventions. Outdated instructions can cause confusion.
Focus on the non-obvious. Do not document things Claude Code can figure out from package.json or configuration files. Focus on team decisions, architectural rules, and gotchas.
Use clear formatting. Use headers, bullet points, and code blocks. Claude Code parses Markdown well, so structure helps.
Test your CLAUDE.md. After writing it, start a new Claude Code session and ask a question that should be answered by your CLAUDE.md. Verify Claude Code follows the instructions.
Key Takeaways
- CLAUDE.md files give Claude Code project-specific instructions that persist across every conversation
- Place the main CLAUDE.md at your project root; add directory-level files for scoped instructions; use ~/.claude/CLAUDE.md for personal preferences
- Include build commands, architecture overview, coding conventions, testing patterns, and explicit "do not" rules
- Keep CLAUDE.md concise and focused on non-obvious information that Claude Code cannot derive from your code alone
- Update your CLAUDE.md as your project evolves to keep Claude Code aligned with current conventions
- The hierarchy reads from most specific (directory-level) to most general (user-level), with specific instructions taking priority