What Is a CLAUDE.md File? The Complete Guide to Project Instructions

What Is a CLAUDE.md File? The Complete Guide to Project Instructions

If you use Claude Code, there is one file that will transform your experience more than any other setting or configuration: the CLAUDE.md file. This guide explains what it is, why it matters, and how to create one that actually works.

The Simple Explanation

A CLAUDE.md file is a markdown file you place in your project's root directory that tells Claude Code about your project. It is like an onboarding document — except instead of onboarding a new team member, you are onboarding an AI.

When you start Claude Code in a directory that contains a CLAUDE.md file, Claude reads it immediately and uses that information to guide every action it takes. Without it, Claude Code can still read your files and figure things out, but with it, Claude Code understands your project's conventions from the very first interaction.

Why Does This Matter?

Imagine hiring a contractor to work on your codebase. They are highly skilled, but they know nothing about your project. They do not know that you use Prisma instead of raw SQL, that your tests go in __tests__ folders next to the source files, that you prefer functional components over class components, or that the utils/ folder is being deprecated in favor of domain-specific helpers.

Without a CLAUDE.md, every session with Claude Code starts from this blank state. Claude will figure out some conventions by reading your code, but it will miss the unwritten rules — the ones that exist only in your team's collective knowledge.

With a CLAUDE.md file, Claude knows all of this before it writes a single line of code.

What Goes in a CLAUDE.md File?

A good CLAUDE.md file typically covers these areas:

Project Overview

A brief description of what the project is, what it does, and what technologies it uses. This gives Claude the big picture.

# Project Overview
This is a SaaS application for team project management.
Built with Next.js 15, TypeScript, Prisma, PostgreSQL, and Tailwind CSS.
Deployed on Vercel with a separate API on Railway.

Architecture and Structure

How your project is organized. Where different types of code live. How the pieces connect.

# Architecture
- `/app` — Next.js app router pages and layouts
- `/lib` — Shared utilities and business logic
- `/lib/db` — Prisma client and database utilities
- `/components` — Reusable UI components
- `/components/ui` — Base design system components (shadcn)
- `/features` — Feature-specific modules with their own components, hooks, and utils

Coding Conventions

The rules your team follows. Naming conventions, patterns to use, patterns to avoid.

# Conventions
- Use functional components with TypeScript
- Prefer named exports over default exports
- Use `server actions` for form mutations, not API routes
- Error handling: use Result types from `/lib/result.ts`, not try-catch
- All database queries go through repository functions in `/lib/db/repos/`

Commands

How to build, test, lint, and deploy the project.

# Commands
- `npm run dev` — Start development server
- `npm run test` — Run vitest
- `npm run test:e2e` — Run Playwright end-to-end tests
- `npx prisma migrate dev` — Run database migrations
- `npm run lint` — ESLint check

Things to Avoid

Explicit instructions about what not to do are often more valuable than what to do.

# Do Not
- Do not use `any` type in TypeScript — use `unknown` and narrow
- Do not create new API routes — use server actions instead
- Do not add dependencies without checking if an existing one covers the use case
- Do not modify files in `/lib/legacy/` — that code is scheduled for removal

Where Does the File Go?

The CLAUDE.md file goes in your project's root directory — the same level as your package.json, Cargo.toml, or whatever your project's main configuration file is.

my-project/
  CLAUDE.md        <-- right here
  package.json
  src/
  tests/
  ...

Claude Code looks for this file automatically when you start it in a directory. No configuration needed. Just create the file and Claude Code will read it.

Nested CLAUDE.md Files

You can also place CLAUDE.md files in subdirectories for more specific instructions. For example, if your API has different conventions than your frontend:

my-project/
  CLAUDE.md              <-- general project instructions
  apps/
    web/
      CLAUDE.md          <-- frontend-specific instructions
    api/
      CLAUDE.md          <-- backend-specific instructions

When Claude Code works on files in apps/web/, it reads both the root CLAUDE.md and the nested one. The nested file adds specificity without overriding the root.

What Makes a Good CLAUDE.md vs a Bad One

Good: Specific and Actionable

When creating new API endpoints, follow this pattern:
1. Define the Zod schema in `/lib/schemas/`
2. Create the server action in `/app/actions/`
3. Add the corresponding repository function in `/lib/db/repos/`
4. Write a test in the adjacent `__tests__` folder

This tells Claude exactly what to do and in what order.

Bad: Vague and Obvious

Write clean code. Follow best practices. Make sure the code works.

This adds no value. Claude already tries to write clean code. Give it specific information it cannot infer from reading your files.

Good: Highlights Exceptions and Gotchas

The `user.email` field is nullable in the database even though the UI requires it.
This is a legacy issue. Always null-check email in backend code.

Bad: Restates What the Code Already Shows

We use React for the frontend. The main component is App.tsx.

Claude can see this by reading the files. Focus on things that are not obvious from the code alone.

CLAUDE.md vs Other Project Documentation

You might wonder how CLAUDE.md relates to your existing README.md or CONTRIBUTING.md files.

README.md is for humans who want to understand and use your project. It covers installation, usage, and high-level description.

CONTRIBUTING.md is for humans who want to contribute. It covers PR processes, code style guides, and development setup.

CLAUDE.md is specifically for Claude Code. It covers the things an AI needs to know to write code that fits your project. There is overlap, but the audience and purpose are different.

Some teams keep their CLAUDE.md very focused on conventions and commands, while others include architectural context that helps Claude make better decisions. Both approaches work.

The Impact on Code Quality

The difference a CLAUDE.md file makes is measurable. Without one, you will frequently need to correct Claude Code:

• "No, we use Prisma, not raw SQL"
• "Put the test file next to the source, not in a separate tests folder"
• "We do not use default exports in this project"

With a good CLAUDE.md, these corrections drop dramatically. Claude gets it right the first time because it knows your rules before it starts writing.

This is especially valuable in larger teams where consistency matters. Every developer using Claude Code on your project gets the same baseline instructions, which means the AI-generated code follows the same conventions regardless of who prompted it.

Getting Started

If you have never created a CLAUDE.md file before, here is the simplest path:

1. Create a file called CLAUDE.md in your project root
2. Add a one-paragraph project overview
3. List your key commands (dev, test, build, lint)
4. Add three to five coding conventions that matter most to your team
5. Add any "do not" rules for common mistakes

You can refine it over time. Every time you find yourself correcting Claude Code about a convention, add that convention to the CLAUDE.md file. After a week or two, your CLAUDE.md will cover the important things naturally.

We have built a free tool that helps you generate a CLAUDE.md file tailored to your project — try the CLAUDE.md generator.

For a hands-on tutorial with a complete example, read our step-by-step CLAUDE.md writing guide.

If you want to go beyond project-level instructions and give Claude domain expertise, check out our guide on Claude Skills — reusable instruction files that make Claude an expert in specific areas.

For more prompting patterns and workflows, visit our prompt library and cheat sheet.