CLAUDE.md — The Complete Guide

CLAUDE.md is the single most important file for getting great results from Claude Code. It is your project's instruction manual for the AI — telling it what your codebase is, how it is structured, what conventions you follow, and what it should or should not do. A well-written CLAUDE.md transforms Claude Code from a general-purpose assistant into a knowledgeable team member who understands your project deeply.

This guide covers everything you need to know about CLAUDE.md: from basic structure to advanced features like hooks, custom commands, and agent teams.

What You'll Learn

• What CLAUDE.md is and how Claude Code reads it
• Optimal file structure and best practices
• Ready-to-use templates for different project types
• Advanced features: hooks, custom commands, agent teams
• CLAUDE.md vs .cursorrules comparison
• India-specific tips for cost optimization

What Is CLAUDE.md?

CLAUDE.md is a markdown file placed in your project root directory. When Claude Code starts a session, it automatically reads this file and uses its contents as persistent system context. Every conversation, every command, and every code generation task starts with the knowledge contained in your CLAUDE.md.

Without CLAUDE.md, you repeat yourself constantly: "This is a Next.js 15 project." "Use App Router, not Pages Router." "The database is PostgreSQL." With CLAUDE.md, Claude Code knows all of this before you type your first message.

Claude Code reads CLAUDE.md files from multiple locations in a hierarchy:

1. ~/.claude/CLAUDE.md — Personal global preferences (applies to all projects)
2. Project root CLAUDE.md — Main project instructions (commit to your repo)
3. Subdirectory CLAUDE.md — Context for specific parts of the codebase

All files are merged, with more specific locations taking priority for conflicting instructions.

CLAUDE.md Structure and Best Practices

A well-structured CLAUDE.md follows a consistent pattern. Here is the recommended structure:

# Project Name — Description

## Overview
Brief description of what the project does and its purpose.

## Tech Stack
| Layer | Technology |
|-------|-----------|
| Frontend | Next.js 15, React 19, TypeScript 5 |
| Backend | .NET Core 9, C# 13 |
| Database | PostgreSQL 16 |

## Project Structure
src/
  app/        — Next.js App Router pages
  components/ — React components
  lib/        — Utilities and API clients

## Coding Conventions
- Use TypeScript strict mode
- Async/await everywhere
- Server Components by default

## Commands
# Start development
npm run dev

# Run tests
npm test

## Do Not
- Never use `any` type
- Never commit .env files

Best practices for writing CLAUDE.md:

• Be specific over general. "Use TypeScript strict mode with no implicit any" is better than "write type-safe code."
• Include exact versions. Claude Code generates better code when it knows you are on Next.js 15 (not 14) or Python 3.12 (not 3.9).
• Show the file structure. Claude Code navigates your project better when it knows where things live.
• List commands. Include the exact commands to build, test, run, and deploy. Claude Code uses these directly.
• State prohibitions clearly. A "Do Not" section prevents recurring mistakes.

CLAUDE.md Templates

Template: Full-Stack Web App

# MyApp — Full-Stack Web Application

## Tech Stack
- Frontend: Next.js 15, React 19, TypeScript 5, Tailwind CSS 4
- Backend: Node.js 22, Express 5, Prisma 6
- Database: PostgreSQL 16
- Auth: NextAuth.js v5
- Hosting: Vercel (frontend), Railway (backend)

## Structure
src/
  app/           — Pages and layouts (App Router)
  components/ui/ — Reusable primitives (Button, Input, Modal)
  components/features/ — Feature components (UserCard, Dashboard)
  lib/           — API client, utils, constants
  hooks/         — Custom React hooks

## Conventions
- Server Components by default; 'use client' only for interactivity
- Tailwind CSS for all styling — no CSS modules
- Named exports for components, default exports for pages only
- All API responses: { data, error, message } shape
- Dates in ISO 8601, currency in INR with ₹ symbol

## Commands
npm run dev          # Start frontend dev server
npm run build        # Production build
npm run test         # Run Playwright E2E tests
npx prisma migrate   # Run database migrations

Template: Python API Service

# Analytics API — Python Microservice

## Tech Stack
- Python 3.12, FastAPI 0.115, SQLAlchemy 2.0 (async)
- PostgreSQL 16, Redis 7 for caching
- Pydantic v2 for validation, Alembic for migrations

## Conventions
- Type hints on ALL functions
- Async handlers everywhere
- Service layer pattern — no business logic in routes
- Use | for union types, not Union[]

## Commands
uvicorn app.main:app --reload   # Dev server
alembic upgrade head            # Run migrations
pytest -x                       # Run tests

Advanced: Hooks and Custom Commands

Claude Code supports hooks — scripts that run automatically at specific lifecycle points. Define them in your .claude/ directory:

Pre-commit hook — runs before Claude Code creates a commit:

{
  "hooks": {
    "pre-commit": "npm run lint && npm run type-check"
  }
}

Custom slash commands let you define reusable workflows. Create files in .claude/commands/:

<!-- .claude/commands/review.md -->
Review the changes in the current branch. Check for:
1. TypeScript type safety
2. Missing error handling
3. Performance concerns
4. Security issues
Provide a summary with severity ratings.

Then invoke it in Claude Code with /review.

Agent Teams

For large projects, CLAUDE.md can define team ownership to prevent different AI agents from stepping on each other's work:

## Team Ownership
### Team 1: Frontend
- src/app/, src/components/, src/hooks/, src/lib/

### Team 2: Backend
- src/api/, src/services/, src/models/

### Team 3: Infrastructure
- docker-compose.yml, .github/workflows/, Dockerfile

When you spawn multiple Claude Code agents in parallel (one per team), each agent respects the ownership boundaries and only modifies files in its designated area. This enables parallel sprint execution with 5 or more agents working simultaneously without conflicts.

CLAUDE.md vs .cursorrules Comparison

| Feature | CLAUDE.md | .cursorrules | |---------|-----------|-------------| | Tool | Claude Code (terminal) | Cursor (IDE) | | Format | Markdown | Plain text | | Location hierarchy | Root + subdirs + global | Root + global settings | | Custom commands | Yes (slash commands) | No | | Hooks support | Yes (pre-commit, etc.) | No | | Agent teams | Yes (team ownership) | No | | Version control | Committed to repo | Committed to repo | | Cost (India) | API: varies / Max: ~₹8,300/mo | Pro: ~₹1,650/mo |

Both tools serve the same core purpose: giving AI persistent project context. If you use both Cursor and Claude Code, maintain both files. Many teams keep them in sync, with CLAUDE.md containing the additional sections for hooks and team ownership.

India-Specific Tips

Cost optimization for Indian developers:

• Claude Pro plan (~₹1,650/month): Includes limited Claude Code usage. Good for individual developers.
• Claude Max plan (~₹8,300/month): Unlimited Claude Code usage. Worth it for full-time AI-assisted development.
• API usage: Pay per token. For cost control, use Claude Haiku for simple tasks and Claude Sonnet for complex ones.
• Free tier stacking: Combine Claude Code (paid) with free Cursor completions and free GitHub Copilot for maximum value.

Add India-specific context to your CLAUDE.md:

## India-Specific
- Currency format: ₹1,00,000 (lakhs/crores system)
- Phone: +91 prefix, 10-digit validation
- Date: DD/MM/YYYY for display, ISO 8601 for storage
- Time zone: IST (UTC+5:30) as default
- GST: include GSTIN validation (15-character alphanumeric)

Internal Resources

Dive deeper into Claude Code with these related guides:

• Claude Code Custom Commands & CLAUDE.md — Create slash commands and configure hooks
• Claude Code Skills & Superpowers — Install and create plugins for Claude Code
• Claude Code CLI Prompts — Ready-to-use prompt templates for Claude Code

Official Resources

• Anthropic Claude Code Documentation — Official Claude Code setup and usage guide
• CLAUDE.md Reference — Official CLAUDE.md specification and examples
• Claude Code GitHub — Source, issues, and community discussions