If you’ve been using Claude Code for a while and wondering why your results feel inconsistent — sometimes brilliant, sometimes off the mark — there’s a good chance you’re missing one thing: the CLAUDE.md file.
It’s one of the least talked-about features in Claude Code, yet experienced developers swear by it. Once you understand what it does and how to use it properly, you’ll never start a project without one again.
What Is CLAUDE.md?
CLAUDE.md is a special markdown file that Claude Code automatically reads at the start of every session. You place it in the root of your project, and Claude uses it as persistent context — a set of instructions, preferences, and project-specific knowledge that carries over into every conversation.
Think of it this way: every time you open a new Claude Code session, Claude starts with a blank slate. It doesn’t remember what you discussed yesterday, what libraries you prefer, or what naming conventions your team follows. Without CLAUDE.md, you’re constantly re-explaining your project from scratch.
With CLAUDE.md, Claude walks into every session already briefed, aligned, and ready to work.
Why Consistency Is Such a Big Problem Without It
Here’s a scenario many developers have experienced:
You ask Claude to write a new API endpoint. It produces clean, readable code using async/await. Great. Later that day, you ask for another endpoint. This time it uses .then() chains. Different style, same task.
Or you ask it to create a new React component. One time it uses functional components with hooks. Another time it generates a class component. The output is technically correct but stylistically inconsistent.
This inconsistency isn’t a bug — it’s just Claude doing its best without enough context. The CLAUDE.md file is how you fix it.
Where to Put CLAUDE.md
Place the file in the root directory of your project. Claude Code will automatically detect and read it when you start a session in that directory.
my-project/
├── src/
├── public/
├── package.json
└── CLAUDE.md ← hereYou can also have multiple CLAUDE.md files in different subdirectories for monorepos or large projects with distinct modules — Claude will read the one closest to the working directory.
What to Put in Your CLAUDE.md File
This is where the real power lies. Here’s a breakdown of the most valuable things to include:
1. Project Overview
Start with a brief summary of what the project is. This gives Claude immediate context about the domain, purpose, and scope.
markdown
## Project Overview
This is a SaaS project management tool built for small teams.
It allows users to create projects, assign tasks, track deadlines,
and collaborate in real time.2. Tech Stack
List every major technology in use — frameworks, languages, databases, authentication libraries, testing tools, and so on.
markdown
## Tech Stack
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Node.js, Express
- Database: PostgreSQL with Prisma ORM
- Auth: Clerk
- Testing: Jest + React Testing Library
- Deployment: Vercel (frontend), Railway (backend)3. Folder Structure
A quick map of your project’s architecture helps Claude navigate confidently without guessing where things live.
markdown
## Folder Structure
- /src/components – Reusable UI components
- /src/pages – Next.js page components
- /src/services – API call functions
- /src/hooks – Custom React hooks
- /src/utils – Helper/utility functions
- /src/types – TypeScript type definitions4. Coding Conventions
This is arguably the most important section. Define your style rules clearly so Claude writes code that fits seamlessly into your existing codebase.
markdown
## Coding Conventions
- Use functional components only (no class components)
- Always use async/await (never .then() chains)
- Use named exports (no default exports)
- All components must have TypeScript interfaces for props
- Use Tailwind for styling — no inline styles or CSS modules
- Error handling: always use try/catch blocks in async functions5. Naming Conventions
Avoid Claude mixing camelCase, PascalCase, and snake_case inconsistently across your project.
markdown
## Naming Conventions
- Components: PascalCase (e.g., UserProfileCard)
- Functions and variables: camelCase (e.g., getUserById)
- Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRY_COUNT)
- Database tables: snake_case (e.g., user_profiles)
- Files: kebab-case (e.g., user-profile-card.tsx)6. What NOT to Do
Don’t just tell Claude what you want — tell it what to avoid. This is incredibly useful for preventing Claude from using deprecated libraries, old patterns, or approaches your team has explicitly moved away from.
markdown
## Do NOT Do These
- Do not use Redux — we use Zustand for state management
- Do not use Axios — we use the native fetch API
- Do not write JavaScript — all files must be TypeScript
- Do not use any — always use proper TypeScript types
- Do not use console.log in production code — use our logger utility7. Common Commands
Include the key commands Claude might need to reference — for running the dev server, running tests, building the project, etc.
markdown
## Common Commands
- Start dev server: `npm run dev`
- Run tests: `npm run test`
- Run linter: `npm run lint`
- Build for production: `npm run build`
- Database migrations: `npx prisma migrate dev`8. Key Business Logic or Domain Rules
If there are important rules specific to your application’s logic that Claude needs to understand, include them here.
markdown
## Business Rules
- A user can belong to multiple organizations
- Free plan is limited to 3 active projects
- Task status flow: To Do → In Progress → In Review → Done
- Only admin users can delete projects
- All timestamps must be stored in UTCA Full CLAUDE.md Example
Here’s what a solid, real-world CLAUDE.md file looks like in practice:
markdown
# CLAUDE.md — Project Context for Claude Code
## Project Overview
TaskFlow is a SaaS task management tool for remote teams.
Users can create workspaces, manage projects, assign tasks,
and track progress with real-time updates.
## Tech Stack
- Frontend: Next.js 14, TypeScript, Tailwind CSS, shadcn/ui
- Backend: Node.js, Express, Prisma ORM
- Database: PostgreSQL (hosted on Supabase)
- Auth: Clerk
- State Management: Zustand
- Testing: Vitest + React Testing Library
## Folder Structure
- /app – Next.js App Router pages
- /components – Reusable UI components
- /lib – Utility functions and helpers
- /hooks – Custom React hooks
- /services – Server-side API logic
- /types – Shared TypeScript interfaces
## Coding Conventions
- Functional components only
- async/await for all async operations
- Named exports throughout
- Strict TypeScript — no "any" types
- Tailwind CSS for all styling
- Error boundaries around all major UI sections
## Naming Conventions
- Components: PascalCase
- Functions/variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Files: kebab-case
## Do NOT Do
- No Redux, no Context API — use Zustand
- No Axios — use fetch
- No class components
- No default exports
- No inline styles
## Commands
- Dev: `npm run dev`
- Test: `npm run test`
- Lint: `npm run lint`
- Build: `npm run build`Tips for Maintaining Your CLAUDE.md
A CLAUDE.md file is only useful if it stays up to date. Here are a few habits to keep it in good shape:
Update it when your stack changes. Add a new library? Remove a deprecated one? Update the file immediately.
Treat it like documentation. Your CLAUDE.md doubles as lightweight onboarding docs for new teammates and for your future self.
Keep it concise but complete. You don’t need to write an essay — bullet points and short sections are perfect. Claude reads them well.
Commit it to version control. Add CLAUDE.md to your Git repository so the whole team benefits and everyone is working with the same setup.
The Bottom Line
The CLAUDE.md file is the single biggest quality-of-life improvement you can make to your Claude Code workflow. It shifts Claude from a general-purpose assistant to a deeply project-aware coding partner that understands your stack, respects your conventions, and delivers consistent results every single time.
Stop re-explaining your project every session. Write it once, commit it to your repo, and let Claude do the rest.
Want more practical tips on AI tools, developer productivity, and the latest in tech? Visit tooltechsavvy.com and follow the blog for fresh content every week. Whether you’re a seasoned developer or just getting started, there’s something there for everyone.
