CLAUDE.md File: Configure Claude Code Like a Pro

TL;DR

• CLAUDE.md is a markdown file Claude Code reads automatically at the start of every session, so it knows your architecture, conventions, and exact build commands instead of guessing from your files.
• It lives in two places: the project root (committed to git, shared with your team) and your home directory (~/.claude/CLAUDE.md, personal and global); when both exist, the project file overrides the global one on conflicts and non-conflicting instructions merge.
• A good CLAUDE.md covers project architecture, coding conventions, build/test/deploy commands, key files, and an explicit "Do NOT" constraints section, which is one of the most valuable parts.
• Keep it specific and under 200 lines, since Claude reads it every session and bloat competes with your code for context; avoid vague advice, secrets, duplicating package.json, or contradicting your linter.
• CLAUDE.md holds static rules (how to work), while .claude/memory.md holds dynamic state (what you are working on now), and the wider .claude/ directory adds settings.json, commands, skills, and agents.

What CLAUDE.md actually does

The CLAUDE.md file is a markdown file that Claude Code reads automatically at the start of every session. It's your project's instruction manual for the AI: a place to define how Claude should work with your specific codebase, what conventions to follow, and what to avoid.

Without a CLAUDE.md, Claude Code reads your files and makes reasonable guesses. With one, it knows your architecture, follows your conventions, runs your exact build commands, and respects constraints you've established. The difference between a bare Claude Code session and one with a well-written CLAUDE.md file is the difference between working with a contractor who just showed up and one who's read the project brief.

If you're new to Claude Code entirely, start with our introduction to Claude Code. If you've already got it installed, this guide covers everything you need to write an effective claude code CLAUDE.md configuration.

Where CLAUDE.md lives

There are two locations for CLAUDE.md files, and they serve different purposes.

Project root (/your-project/CLAUDE.md): This is the primary location. It's checked into git and shared with your team. Everyone who runs Claude Code in this repository gets the same instructions. This is where project-specific rules belong: your tech stack, conventions, build commands, architecture decisions.

Home directory (~/.claude/CLAUDE.md): This is your personal, global configuration. It applies to every project you open with Claude Code. Use it for personal preferences: your preferred formatting style, how you like explanations structured, tools you always want Claude to use.

Precedence rule: When both files exist, the project CLAUDE.md overrides the global one for any conflicting instructions. Your team's project rules always win over personal preferences. Non-conflicting instructions from both files are merged.

What belongs in a CLAUDE.md

A good CLAUDE.md answers the questions Claude would otherwise have to guess at. Here are the categories that matter most.

Project architecture

Tell Claude what it's working with. Not every file, just the structural decisions that aren't obvious from reading package.json.

## Architecture

- Next.js 15 app router, TypeScript strict mode
- Database: Postgres via Drizzle ORM (schema in src/db/schema.ts)
- Auth: NextAuth v5 with GitHub + Google providers
- Styling: Tailwind CSS, no component library
- State: Server components by default, React Query for client state
- API: Server actions preferred over API routes

This saves Claude from guessing whether you use the pages router or app router, whether your ORM is Prisma or Drizzle, whether it should reach for a component library or write Tailwind directly.

Coding conventions

Every team has conventions that aren't captured in ESLint configs. CLAUDE.md is where these live.

## Conventions

- Named exports only, never default exports
- Barrel files (index.ts) in each feature directory
- Database queries go in src/db/queries/, never inline in components
- Error handling: use Result<T, E> pattern, not try/catch for business logic
- File naming: kebab-case for files, PascalCase for components
- Imports: group by external, internal, relative, separated by blank lines

Be specific. "Follow best practices" tells Claude nothing. "Named exports only, never default exports" is a clear rule it can follow every time.

Build, test, and deploy commands

Claude Code can run commands, but it needs to know which ones are correct for your project.

## Commands

- Dev: `pnpm dev` (port 3000)
- Build: `pnpm build` (runs type-check first)
- Test: `pnpm test` (Vitest, run before every commit)
- Test single: `pnpm test -- --filter={filename}`
- Lint: `pnpm lint` (Biome, not ESLint)
- DB migrate: `pnpm db:push` (Drizzle push, NOT migrate)
- Deploy: Push to main triggers Vercel deploy automatically

The specifics matter. If Claude runs npx drizzle-kit migrate when your project uses drizzle-kit push, it will create problems. If it runs npm test when you use pnpm, it will install phantom dependencies.

Key files and directories

Point Claude to the files that matter most so it doesn't have to explore blindly.

## Key Files

- src/db/schema.ts: single source of truth for database schema
- src/lib/auth.ts: auth configuration, session handling
- src/lib/api-client.ts: typed API client, all external calls go through here
- .env.example: required environment variables (never read .env directly)
- src/components/ui/: shared UI primitives (Button, Input, Modal, etc.)

Constraints: things Claude should NOT do

This is arguably the most valuable section. Claude is eager to help, and without explicit constraints it will sometimes "improve" things in ways you don't want.

## Do NOT

- Do not modify the database schema without explicit approval
- Do not install new dependencies without asking first
- Do not use `any` type: find or create the proper type
- Do not add console.log for debugging: use the logger utility at src/lib/logger.ts
- Do not create new API routes: use server actions instead
- Do not put secrets or API keys in any committed file

Negative instructions are powerful. One "do not modify the schema without asking" prevents a category of problems that positive instructions alone can't cover.

Real-world CLAUDE.md examples

Abstract advice only goes so far. Here are three complete CLAUDE.md files for common project types.

Next.js project

# CLAUDE.md

## Overview
E-commerce platform built with Next.js 15, TypeScript, Postgres.
Multi-tenant SaaS, where each store is a subdomain.

## Architecture
- App router with route groups: (marketing), (dashboard), (storefront)
- Drizzle ORM, schema in src/db/schema/
- Stripe for payments, webhooks in src/app/api/webhooks/stripe/
- R2 for file storage via src/lib/storage.ts
- Email via Resend, templates in src/emails/

## Conventions
- Server components by default
- "use client" only when truly needed (interactivity, hooks)
- Named exports, barrel files per feature
- Zod schemas colocated with forms
- All prices stored as cents (integer), formatted at display layer

## Commands
- Dev: `pnpm dev`
- Test: `pnpm vitest run`
- DB: `pnpm db:push` to sync schema, `pnpm db:seed` for test data
- Deploy: Push to main

## Do NOT
- Never modify Stripe webhook handler without approval
- Never use floating point for money calculations
- Never add "use client" to a page component, extract a client component instead
- Never commit .env files

Python/FastAPI project

# CLAUDE.md

## Overview
Internal API for processing insurance claims. FastAPI + SQLAlchemy + Celery.

## Structure
- app/api/: route handlers, grouped by domain (claims/, users/, policies/)
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic models for request/response validation
- app/services/: business logic (keep routes thin)
- app/tasks/: Celery background tasks
- tests/: mirrors app/ structure, pytest

## Conventions
- Type hints on everything, no exceptions
- Services return domain objects, routes handle HTTP concerns
- Background tasks for anything > 500ms (email, PDF generation, external API)
- Alembic for migrations: `alembic revision --autogenerate -m "description"`
- Logging via structlog, not print() or logging module directly

## Commands
- Dev: `uvicorn app.main:app --reload`
- Test: `pytest -x -q` (stop on first failure)
- Lint: `ruff check . && mypy app/`
- Migrate: `alembic upgrade head`

## Do NOT
- Never return SQLAlchemy models directly from routes, always use Pydantic schemas
- Never write raw SQL, use SQLAlchemy query builder
- Never skip the service layer (route to service to model, not route to model)
- Never add dependencies without updating requirements.txt AND requirements-dev.txt

Monorepo with workspace rules

# CLAUDE.md

## Overview
Monorepo: marketing site + web app + shared packages. Turborepo + pnpm workspaces.

## Workspaces
- apps/web: Next.js customer dashboard
- apps/marketing: Astro marketing site
- packages/ui: shared React components (published to npm)
- packages/db: database client and schema (shared between apps)
- packages/config: shared ESLint, TypeScript, Tailwind configs

## Rules
- Changes to packages/ui MUST maintain backward compatibility
- packages/db is the ONLY place that imports from drizzle-orm
- apps/ can import from packages/, never the reverse
- Each package has its own README with API docs, updated when changing exports

## Commands
- Dev all: `pnpm dev` (from root)
- Dev single: `pnpm --filter web dev`
- Test all: `pnpm test`
- Build: `pnpm build` (Turborepo handles ordering)
- Add dep: `pnpm --filter {workspace} add {package}`

## When working in packages/ui
- Every component needs a Storybook story
- Export from index.ts, since consumers only import from package root
- Props interfaces are exported alongside components
- No app-specific logic, components must be generic

These examples share a pattern: they're specific, they're concise, and they tell Claude things it can't infer from the code alone. If you want a head start, Claudify includes 31 production-ready CLAUDE.md templates covering common stacks and project types, see our templates and pricing.

Anti-patterns to avoid

Not all CLAUDE.md files help. Some actively hurt by wasting context tokens or creating confusion.

Too long: Claude has a context window. A 2,000-line CLAUDE.md competes with your actual code for attention. Keep it under 200 lines. If you need more, split details into separate files in .claude/ and reference them.

Secrets in the file: CLAUDE.md is committed to git. Never put API keys, database passwords, tokens, or credentials in it. Use .env files and tell Claude where to find them: "Database credentials are in .env.local, read it when needed."

Too vague: "Write clean code" and "follow best practices" add nothing. Claude already tries to write clean code. Specifics like "use named exports" and "no floating point for money" are what actually change behavior.

Duplicating the obvious: Don't describe what's clear from package.json or tsconfig.json. Claude reads those files. Instead, describe the decisions and conventions that aren't captured in config files: the human knowledge that lives in your team's heads.

Contradicting your tooling: If your ESLint config enforces semicolons, don't write "no semicolons" in CLAUDE.md. Claude will fight your linter. CLAUDE.md should complement your tooling, not contradict it.

The .claude/ directory

Beyond the root CLAUDE.md file, Claude Code recognizes a .claude/ directory for additional configuration. This is where your claude code configuration gets more sophisticated.

.claude/
├── CLAUDE.md          # Additional instructions (merged with root)
├── settings.json      # Tool permissions, model routing, hooks
├── memory.md          # Dynamic state (current tasks, decisions, progress)
├── commands/          # Custom slash commands
│   ├── deploy.md
│   └── test-all.md
├── skills/            # Domain knowledge Claude can load on demand
│   └── database/
│       └── SKILL.md
└── agents/            # Specialist subagent definitions
    └── reviewer.md

settings.json controls tool permissions (which commands Claude can run without asking), hook scripts that run before/after actions, and model preferences. It's the mechanical configuration, while CLAUDE.md is the intellectual configuration.

Commands are reusable procedures written in markdown. When you type /deploy, Claude reads .claude/commands/deploy.md and follows the steps. This is how you encode multi-step workflows.

Skills are domain knowledge files that Claude loads on demand: deeper context about specific areas of your project that would be too large to include in CLAUDE.md directly.

For a deeper look at custom commands and skills, see our guide to Claude Code skills.

CLAUDE.md vs. memory: static rules and dynamic state

A common question is where the line falls between CLAUDE.md and Claude Code's memory systems. The distinction is clean.

CLAUDE.md is for static rules: things that are true about your project regardless of what you're working on today. Your tech stack, conventions, build commands, constraints. These change rarely and apply to everyone on the team.

Memory (.claude/memory.md and related files) is for dynamic state: what you're currently working on, decisions made this week, known issues, progress on open tasks. This changes frequently and is often personal.

# CLAUDE.md (static, committed to git)
## Conventions
- Use server actions, not API routes
- All prices stored as cents

# .claude/memory.md (dynamic, changes often)
## Current Focus
- Building checkout flow, Stripe integration in progress
- Known issue: webhook retry logic not handling idempotency yet

CLAUDE.md tells Claude how to work. Memory tells it what to work on. Together, they give Claude both the rulebook and the current game state.

Team workflows

CLAUDE.md really shines in team environments. Since it's committed to git, every developer on your team gets the same Claude Code behavior.

Shared project rules: The root CLAUDE.md defines team-wide conventions. When a new developer joins and runs Claude Code, they immediately get a session that follows your coding standards, even before they've internalized them.

Personal overrides: Each developer can create ~/.claude/CLAUDE.md for personal preferences that don't affect the team. Maybe you prefer verbose explanations while your colleague prefers terse ones. Maybe you want Claude to always run tests before committing while others handle that manually.

PR consistency: When everyone's Claude Code follows the same CLAUDE.md, pull requests are more consistent. Claude won't use default exports in one developer's branch and named exports in another's.

Onboarding accelerator: A well-written CLAUDE.md doubles as project documentation. New team members read it to understand the project's conventions and architecture, whether or not they use Claude Code.

The key principle: put shared rules in the project CLAUDE.md, put personal preferences in your global ~/.claude/CLAUDE.md, and let the precedence system handle conflicts automatically.

Getting started with your first CLAUDE.md

Start small. You don't need to cover everything on day one. Here's a minimal CLAUDE.md that still makes a meaningful difference:

# CLAUDE.md

## Stack
- [your framework] + [your language]
- [your database] via [your ORM]
- [your key dependencies]

## Commands
- Dev: `[your dev command]`
- Test: `[your test command]`
- Build: `[your build command]`

## Do NOT
- [your most important constraint]
- [your second most important constraint]

Fill in those blanks, save it to your project root, and start a Claude Code session. You'll immediately notice the difference. From there, add sections as you discover gaps: every time Claude guesses wrong about a convention, that's a signal to add a line to your CLAUDE.md.

The best CLAUDE.md files aren't written in one sitting. They evolve as you work with Claude Code and discover what it needs to know. If you want to skip the trial-and-error phase, Claudify's template library includes 31 CLAUDE.md files built from real production projects across the most common stacks, each one refined through actual development use.