CLAUDE.md: The Secret Weapon for Efficient AI Coding

February 10, 2025

Every time you start a new Claude session, you waste tokens explaining your project structure, coding conventions, and preferences. There's a better way: CLAUDE.md files.

What is CLAUDE.md?

A CLAUDE.md file is a markdown file in your project root that Claude Code automatically reads at the start of each session. It gives Claude instant context without you having to explain anything.

Basic Structure

# Project: My Awesome App

## Overview
This is a Next.js 14 app with TypeScript, Tailwind CSS, and Prisma ORM.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma + PostgreSQL
- NextAuth for authentication

## Project Structure
src/
├── app/          # Next.js app router pages
├── components/   # React components
├── lib/          # Utility functions
├── prisma/       # Database schema
└── types/        # TypeScript types

## Coding Conventions
- Use functional components with hooks
- Prefer named exports
- Use 'cn' helper for conditional classes
- Error handling: use try-catch with custom AppError class

## Commands
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run db:push` - Push schema to database
- `npm run db:studio` - Open Prisma Studio

## Important Notes
- Always run `npm run typecheck` before committing
- Environment variables are in .env.local
- API routes require authentication middleware

Why It Works

Without CLAUDE.md, a typical session starts like this:

"What framework is this?" "Where are the components?" "How do you handle errors?" "What's the database setup?"

Each question = more tokens. With CLAUDE.md, Claude already knows everything.

Advanced Tips

Include Common Patterns

## Common Patterns

### Creating a new API route
Always use this structure:
\`\`\`typescript
import { NextResponse } from 'next/server'
import { auth } from '@/lib/auth'

export async function GET(req: Request) {
  const session = await auth()
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  // Your code here
}
\`\`\`

List Your Aliases

## Available Scripts
- `build.sh` - Full build with type checking
- `quick-test.sh` - Run tests for changed files only
- `db-reset.sh` - Reset and seed database

Document Known Issues

## Known Issues
- Hot reload sometimes fails for Tailwind changes (restart dev server)
- Prisma client needs regeneration after schema changes

Multiple CLAUDE.md Files

You can have CLAUDE.md files in subdirectories for specific context:

project/
├── CLAUDE.md              # General project info
├── src/
│   └── components/
│       └── CLAUDE.md      # Component conventions
└── prisma/
    └── CLAUDE.md          # Database specific info

Token Savings

A good CLAUDE.md file can reduce token usage by 30-50% per session by eliminating:

  • Project explanation questions
  • File structure exploration
  • Convention clarification
  • Command lookups

Write it once, save tokens forever.