CLAUDE.md Best Practices: Configure Claude Code for Any Project
CLAUDE.md is the single most impactful configuration for Claude Code. A well-written one turns generic AI assistance into project-specific expertise.
CLAUDE.md is a markdown file at the root of your project. Claude Code reads it at the start of every session before you type anything. A good CLAUDE.md transforms generic AI into a tool that understands your project's conventions, tech stack, and red lines.
What should you include in CLAUDE.md?
Focus on information that a smart developer joining your team would need on day one. Keep it practical: tech stack, commands, conventions, and things to avoid.
Minimal CLAUDE.md template
# Project Context
Next.js 14 app with TypeScript, Tailwind CSS, and Prisma.
Database: PostgreSQL. Auth: NextAuth.js.
## Commands
- `npm run dev` — start dev server (port 3000)
- `npm run test` — run Jest tests
- `npm run lint` — run ESLint
- `npm run db:migrate` — run Prisma migrations
## Architecture
- Server components by default, client components in /components/client/
- API routes in /app/api/ with Zod validation
- Database queries in /lib/db/ (never in components)
## Conventions
- TypeScript strict mode, never use `any`
- Tailwind for styling, no CSS modules
- Conventional commits: feat:, fix:, chore:
## Do NOT
- Modify files in /legacy/ or /vendor/
- Change auth configuration without explicit approval
- Add new dependencies without asking firstWhat are the most common CLAUDE.md mistakes?
| Mistake | Why it hurts | Fix |
|---|---|---|
| Too long (500+ lines) | Wastes context window on every session | Keep under 200 lines, link to docs for details |
| Too vague ("write clean code") | Gives no actionable guidance | Be specific: "Use server components by default" |
| Missing commands | Claude guesses how to run/test/build | List every relevant npm script |
| No restrictions | Claude may modify sensitive files | Add a clear "Do NOT" section |
| Duplicate of README | README is for humans, CLAUDE.md is for AI | Focus on conventions and rules, not project description |
How do you structure CLAUDE.md for large projects?
For large codebases, use the @import syntax to split configuration across directories. Claude Code follows imports and builds a complete picture.
# Root CLAUDE.md
## Global conventions
- TypeScript strict, no `any`
- All API routes validate input with Zod
@import packages/api/CLAUDE.md
@import packages/web/CLAUDE.md
@import packages/shared/CLAUDE.mdEach sub-CLAUDE.md contains rules specific to that package. This keeps the root file short while giving Claude Code deep context about each area of the codebase.
How do you generate CLAUDE.md automatically?
Claude Code can generate a starting CLAUDE.md by analyzing your project:
# Auto-generate CLAUDE.md
claude /init
# This creates a CLAUDE.md based on:
# - package.json scripts
# - Project structure
# - Existing config files
# - Git history patternsStart with /init, then refine manually. The auto-generated file is a good starting point, but it won't know your team's unwritten conventions. Add those yourself.
What about CLAUDE.md memory hierarchy?
Claude Code reads CLAUDE.md files from multiple locations, in order of priority:
- +Project root CLAUDE.md (everyone on the team shares this)
- +Subdirectory CLAUDE.md files (via @import)
- +~/.claude/CLAUDE.md (your personal global preferences)
- +Auto Memory (MEMORY.md, managed by /memory command)
Project-level settings override personal ones. This means team conventions always win over individual preferences.