What Is a CLAUDE.md File? (And Why Every Project Needs One)

The Problem It Solves

Without CLAUDE.md, every new Claude Code session starts the same way: you spend the first few messages explaining what your project is, what framework you are using, and what you were working on. You repeat yourself. Claude gives generic advice because it lacks project context. You waste context window on setup instead of actual work.

With CLAUDE.md, Claude reads your project brief automatically. Your first message can be "continue adding authentication to the user flow" and Claude immediately knows what tech stack to use, where the relevant files are, and what conventions to follow.

What Goes In CLAUDE.md

Think of CLAUDE.md as the briefing document you would give a new developer joining your project. Include:

1. Project overview (2–4 sentences)

What is this project? What does it do? Who is it for?

2. Tech stack

Every major tool in the project. Be specific — include versions if they matter:

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.3
- Database: PostgreSQL via Prisma 6
- Auth: NextAuth.js v5
- Styling: Tailwind CSS 3.4
- Deployment: Vercel
- Package manager: npm

3. Project structure

The key directories and what lives where. Claude cannot navigate your project efficiently without knowing where things are:

## Project Structure
src/app/          - Next.js App Router pages and layouts
src/components/   - Reusable React components
src/lib/          - Utility functions and shared logic
src/lib/db.ts     - Prisma client singleton
prisma/schema.prisma - Database schema
.env.local        - Environment variables (never commit)

4. Architecture decisions

The "why" behind non-obvious choices. Prevents Claude from suggesting alternatives you already considered:

## Architecture Decisions
- Using App Router (not Pages Router) — do not suggest Pages Router patterns
- Server Components by default; use 'use client' only when needed
- All DB queries go through src/lib/db.ts — never import PrismaClient directly
- API routes are in src/app/api/ — not a separate Express server

5. Coding conventions

Your preferences for naming, patterns, and style:

## Conventions
- TypeScript: strict mode, no 'any' types
- Components: functional, named exports (not default exports)
- File names: kebab-case for files, PascalCase for components
- Error handling: always use try/catch in server actions
- CSS: Tailwind classes only — no custom CSS files

6. Common commands

Commands Claude should know when it needs to run something:

## Common Commands
npm run dev          - Start dev server (port 3000)
npm run build        - Production build
npm run lint         - ESLint check
npx prisma studio    - Open database GUI
npx prisma migrate dev --name [name]  - Create migration

7. Current work / known issues (optional, update regularly)

## Current Work
- Building user authentication flow (in progress)
- TODO: add email verification step after signup
- KNOWN BUG: profile image upload fails on Safari (src/components/ImageUpload.tsx)

Complete CLAUDE.md Example

# My SaaS App — Claude Context

## Project
A project management tool for freelancers. Users create projects, track time,
and generate invoices. Built as a Next.js SaaS with Stripe billing.

## Tech Stack
- Next.js 15 (App Router), TypeScript 5.3
- PostgreSQL + Prisma 6 ORM
- NextAuth.js v5 (GitHub + Google OAuth)
- Stripe for billing
- Tailwind CSS 3.4
- Deployed on Vercel (frontend) + Railway (database)

## Project Structure
src/app/             App Router pages
src/app/api/         API route handlers
src/components/      Reusable components (PascalCase files)
src/lib/db.ts        Prisma client (singleton pattern)
src/lib/stripe.ts    Stripe client
prisma/schema.prisma Database schema

## Architecture Decisions
- Server Components by default — 'use client' only for interactive UI
- All Stripe webhooks go through /api/webhooks/stripe/route.ts
- Never query the DB directly from components — use server actions in actions/
- Auth is handled by NextAuth — do not roll custom session logic

## Conventions
- No 'any' TypeScript types — use proper interfaces
- Named exports for all components and utilities
- Error boundaries at the page level
- Validate all user input with Zod before DB writes

## Common Commands
npm run dev           Start dev server
npx prisma studio     Database GUI
npx prisma migrate dev --name [name]   New migration
npm run build && npm start             Test production build locally

Equivalent Files for Other AI Tools

• Cursor: .cursorrules in project root
• Windsurf: .windsurfrules in project root
• GitHub Copilot: .github/copilot-instructions.md
• Claude Code: CLAUDE.md (this article)

The concept is the same across tools — a project-level instructions file that gives the AI persistent context. If you switch tools, copying your CLAUDE.md content to .cursorrules takes about 30 seconds.

What to Learn Next

• Claude Code Beginner's Guide — Full guide to Claude Code CLI and how CLAUDE.md fits into the workflow.
• AI Prompting Guide for Coders — Write better prompts to complement your CLAUDE.md context.
• Cursor Beginner's Guide — Cursor's equivalent of CLAUDE.md is .cursorrules.

FAQ