Why I Started Using CLAUDE.md Files
When I first started using Claude Code across multiple projects, I kept running into the same frustrating problem. I'd spend time explaining my project structure, coding standards, and preferences to Claude, only to have to repeat everything again in the next conversation.
For my React projects, I wanted Claude to know I prefer functional components and TypeScript. For my Python scripts, I needed it to understand my specific file organization. And for client work, I had different naming conventions entirely.
That's when I discovered CLAUDE.md files – a game-changer that lets you set project-specific instructions that Claude remembers automatically.
What Are CLAUDE.md Files?
A CLAUDE.md file is like a configuration file for Claude Code that sits in your project root. Think of it as a permanent set of instructions that Claude reads every time you work on that specific project.
Instead of explaining your preferences over and over, you write them once in this file, and Claude automatically applies them to all conversations in that project directory.
File Location Matters
The CLAUDE.md file must be in your project's root directory to work properly. Claude looks for it there automatically.
Creating Your First CLAUDE.md File
Let me show you how I set up a CLAUDE.md file for one of my recent projects. I'll walk you through creating one step by step.
First, create the file in your project root:
# Navigate to your project root
cd my-project
# Create the CLAUDE.md file
touch CLAUDE.mdNow, here's what I typically include in my CLAUDE.md files. I start with basic project information:
# Project: Task Management App
## Tech Stack
- React 18 with TypeScript
- Tailwind CSS for styling
- Vite for build tooling
- React Query for data fetching
## Coding Preferences
- Use functional components only
- Prefer const assertions for arrays
- Use named exports instead of default exports
- Keep components under 100 lines when possibleEssential Sections for Your CLAUDE.md
Through trial and error, I've found these sections make the biggest difference in how Claude Code helps with my projects:
Project Structure: I always include how my files are organized. This helps Claude understand where to create new files and how to import things correctly.
## Project Structure
```
src/
components/ # Reusable UI components
pages/ # Page-level components
hooks/ # Custom React hooks
utils/ # Utility functions
types/ # TypeScript type definitions
```Naming Conventions: This saves so much back-and-forth. I specify exactly how I want files and functions named.
## Naming Conventions
- Components: PascalCase (TaskCard.tsx)
- Hooks: camelCase starting with 'use' (useTaskData.ts)
- Utils: camelCase (formatDate.ts)
- Types: PascalCase with 'T' prefix (TTask, TUser)Code Style: I include specific preferences that matter to me, like how I want error handling or state management done.
Real Examples That Work
Let me share a few CLAUDE.md examples from my actual projects. Here's one from a Python data analysis project:
# Data Analysis Project
## Environment
- Python 3.9+
- pandas, numpy, matplotlib, seaborn
- Jupyter notebooks for exploration
- .py files for reusable functions
## Code Standards
- Follow PEP 8 style guide
- Use type hints for all functions
- Include docstrings for complex functions
- Keep functions under 20 lines when possible
## Data Handling
- Always validate data before processing
- Use descriptive variable names
- Log data transformation stepsAnd here's one from a WordPress project where I needed Claude to understand my custom theme structure:
# Custom WordPress Theme
## Theme Structure
- templates/ # Block theme templates
- parts/ # Template parts
- assets/ # CSS, JS, images
- inc/ # PHP includes and functions
## WordPress Preferences
- Use block theme patterns
- Follow WordPress coding standards
- Enqueue assets properly in functions.php
- Use get_template_directory_uri() for asset pathsMaking Claude Remember Your Context
One of the most powerful things you can include in your CLAUDE.md file is project context. I learned this lesson when working on a client project where Claude kept suggesting generic solutions instead of understanding the specific business requirements.
Now I always include a context section:
## Project Context
This is an internal tool for managing customer support tickets.
Users are non-technical support staff who need simple, clear interfaces.
Performance matters - we handle 1000+ tickets daily.
## Key Requirements
- Mobile-first design (staff use tablets)
- Offline capability for basic functions
- Integration with existing CRM system
- GDPR compliance for customer dataThis context helps Claude make better suggestions that actually fit your project's real-world constraints.
Keep It Updated
I update my CLAUDE.md files as projects evolve. When you add new dependencies or change coding standards, update the file so Claude stays in sync.
Testing Your CLAUDE.md Setup
After creating your CLAUDE.md file, test it by starting a new conversation with Claude Code in that project. Ask it to create a simple component or function and see if it follows your specified conventions.
When I first set up CLAUDE.md files, I'd ask Claude something like "Create a new user profile component" and watch to see if it used my preferred file structure, naming conventions, and coding style without me having to explain them again.
If Claude isn't following your instructions, check that:
• The file is named exactly CLAUDE.md (all caps)
• It's in the project root directory
• Your instructions are clear and specific
• You've restarted Claude Code after creating the file
Start Simple, Then Expand
My advice? Start with a basic CLAUDE.md file covering just your essential preferences, then add to it as you work on the project. I usually begin with tech stack, basic coding preferences, and file structure. Then I add more specific instructions as I discover what would be helpful.
The goal isn't to write a perfect CLAUDE.md file from day one – it's to stop repeating yourself and let Claude Code understand your project better from the start. Even a simple file with your basic preferences will save you time and frustration.
Once you get used to creating these files, you'll wonder how you ever worked on projects without them. They're one of those small changes that make a surprisingly big difference in your daily workflow.
Want to go deeper?
Check out more tutorials in this category, or explore the full site.