What Is a CLAUDE.md File?
The CLAUDE.md file is the heart of Claude Code customization. It lets you define persistent instructions that guide the AI assistant's behavior in your project. Unlike regular prompts you type each conversation, CLAUDE.md stays in memory and applies automatically.
Why It Matters
Imagine having to explain every time to your assistant:
- Which framework you use
- Your code conventions
- Files that should never be modified
- Your preferred comment style
With a well-written CLAUDE.md, all of this is configured once.
Creating Your First CLAUDE.md
Step 1: Create the File at the Project Root
Place a .claude/CLAUDE.md or CLAUDE.md file at the root of your Git repository. Claude Code will detect it automatically.
mkdir -p .claude
touch .claude/CLAUDE.md
Step 2: Define the Project Context
Start by describing your project in a few lines:
# My Project
## Tech Stack
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- ORM: Drizzle
Step 3: Add Code Conventions
Specify your development preferences:
## Conventions
- Use arrow functions for React components
- Name files in kebab-case
- Always type props with interfaces
- No any, use unknown if necessary
Step 4: Define Restrictions
Equally important is what Claude should not do:
## Restrictions
- Never modify existing migration files
- Do not add dependencies without asking
- Do not delete existing TODO comments
Structuring Your CLAUDE.md Effectively
The Recommended Structure
A good CLAUDE.md follows this structure:
- Project description (2-3 lines)
- Tech stack (list of technologies)
- Architecture (important folder structure)
- Code conventions (style, naming, patterns)
- Useful commands (build, test, deploy)
- Restrictions (what not to do)
Complete Example
Here is a CLAUDE.md example for a SaaS application:
# TaskFlow - Task Management Application
## Stack
- Next.js 14 (App Router)
- Tailwind CSS + shadcn/ui
- Supabase (auth + DB)
- Stripe (payments)
## Architecture
- /app: Routes and pages
- /components: Reusable components
- /lib: Utilities and configurations
- /hooks: Custom React hooks
## Conventions
- Components in PascalCase
- Hooks prefixed with use
- Server Components by default
- Client Components only when necessary
## Commands
- npm run dev: Development server
- npm run build: Production build
- npm run test: Unit tests
## Do Not
- Do not use getServerSideProps (App Router)
- Do not install additional CSS packages
- Do not modify the Supabase schema directly
Advanced Best Practices
Using Shared Skills
Your CLAUDE.md can reference community skills with the @ directive:
@typescript-strict.md
@react-best-practices.md
This lets you combine your personal instructions with community-maintained skills.
Version Control Your CLAUDE.md
Add your CLAUDE.md to Git. This lets the whole team benefit from the same instructions and track changes over time.
Iterate and Improve
Your CLAUDE.md is not set in stone. Improve it as you go:
- Add rules when Claude makes recurring mistakes
- Remove rules that are no longer needed
- Ask Claude to help you optimize it
Tip: Ask Claude "Analyze my CLAUDE.md and suggest improvements" to get recommendations.
Common Mistakes to Avoid
1. Being Too Vague
Bad: "Write good code" Good: "Use descriptive variable names in camelCase, add explicit TypeScript types"
2. Being Too Restrictive
A CLAUDE.md that is too long with too many rules can become counterproductive. Keep essential instructions and trust the model for the rest.
3. Not Maintaining the File
An outdated CLAUDE.md is worse than no CLAUDE.md at all. Review it regularly.
Conclusion
The CLAUDE.md file is your best ally for getting the most out of Claude Code. By investing 30 minutes in its creation, you will save hours of productivity in every development session.
Explore our skills library to find ready-to-use templates and check out the advanced guides to go further.