CLAUDE.md: The Complete Guide to Project-Specific Claude Code Instructions

There’s a file most Claude Code tutorials barely mention — a file that, once you understand it, changes how you use Claude Code entirely.

That file is CLAUDE.md.

Every time you start a Claude Code session in a directory that contains a CLAUDE.md file, Claude reads it automatically before anything else. It becomes part of the context for every task, every response, every decision Claude makes in that project.

Set it up well and Claude behaves like it’s been working on your codebase for months — already knowing your conventions, your constraints, your tech stack, and your preferences. Skip it and you spend 20% of every session explaining the same context you explained yesterday.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file you place at the root of any project. Claude Code picks it up automatically and treats its contents as standing instructions that persist across the entire session.

There’s no special syntax. No API to call. Just a Markdown file with whatever you want Claude to know about your project at all times.

Think of it as the project’s README — but written for Claude Code rather than humans.

Where Does CLAUDE.md Live?

Claude Code looks for CLAUDE.md in several places, with a clear precedence order:

1. ~/.claude/CLAUDE.md — global user-level instructions, applies to every project
2. ./CLAUDE.md — project-level instructions (root of your repo)
3. Subdirectory CLAUDE.md files — scoped to that subdirectory

The global file is great for your personal preferences and tools you always use. The project file is for project-specific conventions and context.

What to Put in CLAUDE.md

The most effective CLAUDE.md files cover four categories: project context, technical conventions, constraints, and workflow preferences.

1. Project Context

Give Claude the mental model it needs to make good decisions:

# Project: Acme Payment Gateway

## What This Is
A REST API for processing payments in the US market. Built with Node.js, Express, 
PostgreSQL. Deployed on AWS ECS. PCI DSS Level 1 compliant.

## Business Rules
- Never log card numbers, CVVs, or full SSNs anywhere
- All dollar amounts stored as integers (cents) — never floats
- Idempotency keys required on all payment endpoints
- US-only for now — no multi-currency logic yet

This context prevents costly mistakes. Without it, Claude might log sensitive data, introduce float arithmetic for money, or add multi-currency code you don’t need yet.

2. Technical Conventions

Your team’s style decisions that aren’t obvious from the code:

## Tech Stack
- Node.js 22, Express 5, TypeScript 5.4
- PostgreSQL 16 via pg (not TypeORM, not Prisma — direct SQL)
- Jest for tests, supertest for API tests
- ESLint + Prettier (run with `npm run lint`)

## Conventions
- Use async/await — never .then()/.catch()
- Error handling: throw typed errors, catch at route level
- Always validate request bodies with zod schemas
- SQL: write raw queries, no query builders
- Branch names: feat/TICKET-ID-description

Without this, Claude will default to its training data preferences — which may mean Prisma when you want raw SQL, or callbacks when you want async/await.

3. Constraints and Anti-Patterns

Things Claude should never do in this project:

## Do Not
- Add any new npm dependencies without asking first
- Modify the database schema without a migration
- Use console.log in production code (use the logger import)
- Write tests that hit the real database (use the test DB fixture)
- Commit .env files or any secrets
- Use `var` — always `const` or `let`

This is especially valuable for large autonomous tasks where Claude makes many decisions independently. Explicit prohibitions prevent the kinds of errors that are hard to catch in code review.

4. Workflow Preferences

How you want Claude to work, not just what you want it to build:

## Workflow
- Don't create files unless necessary — edit existing ones first
- When fixing bugs: root cause analysis before any code change
- After editing: check if tests pass with `npm test`
- For new features: check if there's an existing pattern to follow first
- Commit format: "type(scope): description" — e.g. "fix(auth): handle expired tokens"

A Real-World CLAUDE.md Example

Here’s a complete CLAUDE.md for a SaaS product:

# Projectify — Task Management SaaS

## Overview
Multi-tenant SaaS for project management. React + TypeScript frontend, 
Node.js + Express backend, PostgreSQL via Supabase, deployed on Vercel.
~1,200 paying customers. Production traffic is live.

## Architecture
- `/apps/web` — Next.js 14 frontend (App Router)
- `/apps/api` — Express API (Node 22)
- `/packages/db` — Shared Prisma schema and client
- `/packages/types` — Shared TypeScript types

## Key Conventions
- Multi-tenant: every DB query must filter by `organization_id`
- Auth via Clerk — use `auth()` from @clerk/nextjs for session
- Payments via Stripe — never store card data
- File uploads go to S3, URLs stored in DB
- All dates stored/manipulated in UTC

## Do Not
- Query across tenants (will expose data to wrong org)
- Add columns to the users table (Clerk manages users)
- Use `fetch()` directly — use our `api` client from /packages/types
- Deploy untested code (staging → production only)

## Dev Commands
- `npm run dev` — start all services with turbo
- `npm run test` — run all tests
- `npm run db:push` — push schema changes (dev only)
- `npm run lint:fix` — auto-fix lint issues

## Current Sprint Focus
Working on CSV import feature (PROJ-847). Don't refactor unrelated code.

This file tells Claude everything it needs to work autonomously on the codebase — without a 5-minute context dump at the start of every session.

Keeping CLAUDE.md Updated

The most common mistake is creating a good CLAUDE.md and never touching it again. Keep it current:

• Sprint notes — add the current focus area and ticket numbers
• Recent decisions — capture architectural choices that future-you would wonder about
• New constraints — when you decide something, add it immediately
• Remove outdated rules — stale instructions create confusion

A lean, accurate CLAUDE.md beats a comprehensive stale one.

The Global CLAUDE.md

Your ~/.claude/CLAUDE.md applies globally across every project. Use it for:

# My Preferences (global)

## Always
- Write code I can read and maintain easily
- Explain non-obvious decisions in comments
- Check if a test exists before writing a new one
- Use the project's existing patterns, not new ones

## My Stack
I mostly work with: TypeScript, Python, PostgreSQL, AWS.
When I say "deploy" I usually mean AWS ECS or Lambda.
When I say "queue" I usually mean SQS.

## Code Style
- Prefer explicit over clever
- Flat is better than nested
- Short functions over long ones
- Name things for what they do, not how they're implemented

This is your personal LLM configuration file — it trains Claude Code on how you think and how you prefer to work.

CLAUDE.md vs Skills

Both CLAUDE.md and Claude Code skills give Claude instructions. The difference:

They’re complementary. CLAUDE.md gives Claude the context to work in your project safely. Skills give Claude the specialized procedures to do specific tasks well. Use both. For a deep dive into the slash command system that triggers skills, see the Claude Code slash commands guide.

Common Patterns

For solo projects: Start simple — just tech stack, key conventions, and 5-10 “do not” rules. Expand as you notice repeated misunderstandings.

For team projects: Use CLAUDE.md to encode your team’s agreed standards so Claude behaves consistently regardless of who’s running it.

For client work: Create a CLAUDE.md per client repo with their specific tech choices and constraints. Never explain the same stack twice.

For SaaS products: Include business rules that prevent critical errors (don’t query across tenants, don’t log PII, all money in cents). The cost of a wrong assumption in a SaaS codebase is high.

With hooks: CLAUDE.md controls Claude’s behavior during a session. Hooks control what happens after each tool use — running tests, committing code, sending Slack notifications. They work together: CLAUDE.md sets the intent, hooks enforce it at the system level.

Your CLAUDE.md is the difference between Claude Code as a generic coding assistant and Claude Code as a developer who knows your codebase. Ten minutes writing a good one saves that time back on the first session. Pair it with a memory system for longer-running projects — CLAUDE.md handles project context, memory handles evolving state.

Looking to pair a well-configured CLAUDE.md with production-grade skills? The Claude Skills 360 bundle includes 2,350+ pre-built skills across 18 domains — from code development to financial analysis to marketing automation. Get started for free with 360 skills and a 90-second install.