CLAUDE.md Guide: Configure Claude Code Like a Pro

What is CLAUDE.md?

CLAUDE.md is a special markdown file that provides persistent context to Claude Code. Place it in your project root and Claude Code reads it automatically every session.

Think of it as a README for your AI — it tells Claude Code how your project works and how you want it to behave.

Basic Template

# Project Name

## Overview
Brief description of what this project does.

## Tech Stack
- Frontend: React 19 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- ORM: Drizzle
- Testing: Vitest + Playwright

## Project Structure
- src/app/ — Next.js app router pages
- src/components/ — Reusable UI components
- src/lib/ — Utility functions and configurations
- src/api/ — API route handlers

## Coding Conventions
- Use functional components with hooks
- Prefer named exports
- Use TypeScript strict mode
- All files must pass ESLint
- Write tests for all new features

## Common Commands
- `npm run dev` — Start development server
- `npm run test` — Run test suite
- `npm run build` — Production build
- `npm run lint` — Lint check

Advanced Template

# Enterprise SaaS App

## Architecture
Monorepo using Turborepo:
- apps/web — Next.js frontend
- apps/api — Express backend
- packages/ui — Shared component library
- packages/db — Database schema and migrations

## Database
- PostgreSQL 16 with Drizzle ORM
- Migrations in packages/db/migrations/
- Always create a migration for schema changes
- Never modify existing migrations

## Authentication
- Clerk for auth (configured in apps/web/middleware.ts)
- JWT tokens for API auth
- All API routes require authentication except /api/health

## API Conventions
- RESTful endpoints under /api/v1/
- Response shape: { data, error, meta }
- Use Zod for request validation
- Rate limiting on all endpoints

## Testing
- Unit tests: Vitest (run: pnpm test)
- E2E tests: Playwright (run: pnpm test:e2e)
- Minimum 80% coverage for new code

## Deployment
- main branch → production (Vercel)
- dev branch → staging
- Always create PR, never push directly to main

## Do NOT
- Use 'any' type in TypeScript
- Skip error handling
- Commit .env files
- Use inline styles (use Tailwind)

Best Practices

1. Be specific — Vague instructions produce vague code
2. Include commands — So Claude Code can run tests/builds
3. Document conventions — Coding style, naming, patterns
4. List “Do NOT” rules — Explicit prohibitions save token waste
5. Keep it updated — As the project evolves, update CLAUDE.md
6. Include architecture — Help Claude understand the big picture

Nested CLAUDE.md Files

You can place CLAUDE.md files in subdirectories for context-specific instructions:

project/
├── CLAUDE.md              # Global project context
├── src/
│   ├── frontend/
│   │   └── CLAUDE.md      # Frontend-specific rules
│   └── backend/
│       └── CLAUDE.md      # Backend-specific rules

Related Articles

• Claude Code Tips & Tricks — Power user
• Claude Code for Beginners — Getting started
• Claude MCP Guide — External tools
• Install Claude Code — Setup guide