How to Create a CLAUDE.md Configuration File for Claude Code

How to Create a CLAUDE.md Configuration File — And Why It Changes Everything

If you have used Claude Code and felt like it needed too much hand-holding at the start of every session, the fix is a single file: CLAUDE.md.

Claude Code reads this file automatically when it opens your project. It learns your stack, your conventions, your commands, and your rules — before you type a single prompt. Every session starts with full context instead of zero context.

This tutorial covers exactly how to create a CLAUDE.md file, what to put in it, and real templates you can drop into your project today.

🎯 Quick Answer (30-Second Read)

What it is: A Markdown file at the root of your project that Claude Code reads automatically on every session start
What it does: Gives Claude persistent context about your stack, commands, conventions, and rules
Where it lives: Project root as CLAUDE.md — committed to your repo
Biggest benefit: Eliminates repetitive context-setting at the start of every Claude Code session
Also works: Sub-folders can have their own CLAUDE.md for module-specific instructions
Who needs it: Any developer using Claude Code on a real project with more than one session

What Is a CLAUDE.md File

CLAUDE.md is a plain Markdown file that Claude Code automatically reads at the start of every conversation. It is Claude Code's equivalent of a system prompt — but for your project, not your AI tool.

When you open a project in Claude Code, it looks for CLAUDE.md in the current directory and any parent directories. It reads the contents and loads them into its working context before you say anything.

Think of it as onboarding documentation written specifically for Claude. A new human developer joining your team would read a README. Claude reads CLAUDE.md.

The file can contain anything Claude needs to work effectively:

Project overview — what the app does, who uses it
Tech stack — frameworks, libraries, runtime versions
Common commands — how to run, test, build, and deploy
Coding conventions — naming patterns, file structure, style rules
Do not touch rules — files or patterns Claude should never modify
Architecture notes — where key logic lives, how modules connect

Step-by-Step: How to Create Your CLAUDE.md File

Step 1 — Create the file at your project root

touch CLAUDE.md

Place it at the same level as your package.json, pyproject.toml, or root config file. Claude Code searches from the current working directory upward.

Step 2 — Add a project overview section

Start with a short description of what the project is. Claude uses this to anchor every decision it makes.

## Project Overview

This is a SaaS dashboard built with Next.js 14 App Router and Supabase.
Users manage subscription billing through Stripe. The app is deployed on Vercel.

Step 3 — Document your tech stack explicitly

Do not assume Claude knows your exact versions and choices. Be explicit.

## Tech Stack

- **Framework:** Next.js 14 (App Router, not Pages Router)
- **Language:** TypeScript 5.x — strict mode enabled
- **Database:** Supabase (PostgreSQL) with Prisma ORM
- **Auth:** Supabase Auth with middleware-based route protection
- **Styling:** Tailwind CSS + shadcn/ui components
- **Payments:** Stripe (subscriptions + webhooks)
- **Deployment:** Vercel (preview + production environments)
- **Package manager:** pnpm — never use npm or yarn

Step 4 — Add your common development commands

This is one of the highest-value sections. Claude can now run the right commands without asking you every time.

## Common Commands

| Task | Command |
|---|---|
| Start dev server | `pnpm dev` |
| Run all tests | `pnpm test` |
| Run a single test file | `pnpm test src/lib/auth.test.ts` |
| Type check | `pnpm typecheck` |
| Lint | `pnpm lint` |
| Build for production | `pnpm build` |
| Database migration | `pnpm db:migrate` |
| Seed database | `pnpm db:seed` |
| Generate Prisma client | `pnpm db:generate` |

Step 5 — Define your coding conventions

This is where you prevent Claude from generating code that looks foreign to your codebase.

## Coding Conventions

- Use named exports everywhere — no default exports except for Next.js pages
- All components live in `src/components/` — UI primitives in `src/components/ui/`
- Server actions live in `src/actions/` and are prefixed with the domain (e.g. `billing.actions.ts`)
- All API routes use the Next.js Route Handler pattern — no `pages/api/`
- Use `zod` for all input validation — never trust raw request bodies
- Error handling uses a custom `AppError` class defined in `src/lib/errors.ts`
- All database queries go through `src/lib/db.ts` — never import Prisma client directly

Step 6 — Set hard rules for what Claude should never do

This prevents Claude from making destructive or unwanted changes.

## Rules — Read Before Every Task

- NEVER modify `src/lib/stripe.ts` — payment logic is frozen until further notice
- NEVER change the Prisma schema without being explicitly asked
- NEVER install new dependencies without asking first
- NEVER delete files — mark them with a TODO comment instead
- ALWAYS run `pnpm typecheck` after making changes to TypeScript files
- ALWAYS write tests for new utility functions in `src/lib/`

Step 7 — Add architecture notes for complex areas

Help Claude navigate the non-obvious parts of your codebase.

## Architecture Notes

**Authentication flow:**
Auth is handled by Supabase. Middleware in `src/middleware.ts` protects all `/dashboard` routes.
The session is available server-side via `createServerClient` from `@supabase/ssr`.

**Billing flow:**
Stripe webhooks hit `/api/webhooks/stripe`. The handler in `src/app/api/webhooks/stripe/route.ts`
processes events and updates the `subscriptions` table via `src/lib/billing.ts`.

**Component patterns:**
Server components fetch data directly. Client components receive data as props.
Use `"use client"` only when interactivity or browser APIs are required.

Step 8 — Commit the file to your repository

git add CLAUDE.md
git commit -m "Add CLAUDE.md for Claude Code configuration"

Every developer on your team now gets the same Claude behavior.

Complete CLAUDE.md Template

Here is a production-ready template you can copy and adapt:

# CLAUDE.md — Project Configuration for Claude Code

## Project Overview
[Describe what the app does in 2-3 sentences. Who uses it, what problem it solves.]

## Tech Stack
- **Framework:** 
- **Language:** 
- **Database:** 
- **Auth:** 
- **Styling:** 
- **Deployment:** 
- **Package manager:** 

## Common Commands
| Task | Command |
|---|---|
| Dev server | `` |
| Tests | `` |
| Type check | `` |
| Lint | `` |
| Build | `` |

## Project Structure
- `src/app/` — Next.js App Router pages and layouts
- `src/components/` — Reusable React components
- `src/lib/` — Utility functions and shared logic
- `src/actions/` — Server actions
- `src/types/` — Shared TypeScript types

## Coding Conventions
- [List your naming conventions]
- [List your import patterns]
- [List your file organization rules]
- [List your error handling approach]

## Hard Rules
- NEVER [action that would break the project]
- ALWAYS [action that must happen after changes]
- DO NOT [pattern to avoid]

## Architecture Notes
[Explain any non-obvious systems: auth flow, payment flow, background jobs, etc.]

## Environment Variables
- `DATABASE_URL` — Supabase connection string
- `STRIPE_SECRET_KEY` — Stripe API key
- `NEXT_PUBLIC_SUPABASE_URL` — Public Supabase URL
[Add all env vars so Claude knows what is available]

Advanced CLAUDE.md Patterns

Nested CLAUDE.md files — place a CLAUDE.md inside a subdirectory for module-specific rules. Claude Code merges parent and child instructions. Use this for monorepos where packages/api/ and packages/web/ have different conventions.

Referencing other files — use relative paths to point Claude to important files:

## Key Files
- Auth logic: `src/lib/auth.ts`
- Database client: `src/lib/db.ts`
- Global types: `src/types/index.ts`
- Environment config: `src/config/env.ts`

Session-specific overrides — if you need to override CLAUDE.md rules for a specific task, just say so in your prompt. Claude treats direct instructions as higher priority than the config file.

Comparison: With vs Without CLAUDE.md

Scenario	Without CLAUDE.md	With CLAUDE.md
First prompt of session	Must explain stack and conventions	Claude already knows the project
Running tests	Must specify the test command	Claude runs `pnpm test` automatically
New component	May use wrong patterns or exports	Follows your conventions from the start
Database changes	May modify schema unexpectedly	Knows to never touch schema without permission
Multi-developer team	Inconsistent Claude behavior per developer	Consistent behavior for everyone
Onboarding new dev	They re-explain everything each session	They inherit your configured context

Real Developer Use Case

A developer maintaining a large Next.js monorepo with three packages used Claude Code without CLAUDE.md for two weeks. Every session started with five minutes of context-setting: which package they were in, which test runner to use, which components were off-limits.

After adding a CLAUDE.md to each package root with stack details, commands, and hard rules, the onboarding cost per session dropped to zero. Claude picked up the right test runner, used the correct import paths, and respected frozen files — automatically.

The team then standardized the CLAUDE.md format across all projects. New engineers joining the team got consistent Claude behavior from day one, without needing to learn the prompting conventions themselves.

Frequently Asked Questions

Where exactly should CLAUDE.md be placed?
Place it at the root of your project — the same directory where you run your dev commands. For monorepos, place one at the repo root and additional CLAUDE.md files inside each package or app subdirectory. Claude Code reads and merges them based on the current working directory.

Does CLAUDE.md work with Cursor too?
CLAUDE.md is specific to Claude Code. Cursor uses a different context system — it indexes your codebase and uses .cursorrules for custom instructions. If you use both tools, maintain separate config files. The conventions you document in CLAUDE.md can be copy-pasted into .cursorrules with minimal changes.

Should CLAUDE.md be committed to the repository?
Yes. Committing it ensures every developer on your team gets the same Claude Code behavior. It also serves as living documentation of your project conventions. Treat it like a CONTRIBUTING.md that is written for an AI audience.

How long should a CLAUDE.md file be?
Aim for 100–300 lines for most projects. Enough to cover stack, commands, conventions, and rules — not so long that important rules get buried. If yours exceeds 500 lines, split it into a root file and module-specific files in subdirectories.

Can I have Claude generate my CLAUDE.md automatically?
Yes — and this is a great way to start. Open your project in Claude Code and prompt: "Read my project structure, package.json, and key config files, then generate a CLAUDE.md file covering my stack, common commands, and suggested conventions." Review the output, adjust the rules, and commit it.

Conclusion

CLAUDE.md is the highest-leverage configuration change you can make to your Claude Code workflow. One file. Committed once. Every session starts with full project context from that point forward.

Create it if you: use Claude Code on any real project, work in a team, or find yourself repeating the same project context every session.

The ten minutes it takes to write a good CLAUDE.md saves hours of repeated context-setting across every future Claude Code session — and makes every AI-assisted task in your codebase more accurate from the first prompt.