CLAUDE.md: The Template Guide for AI-Assisted Codebases

What Is CLAUDE.md?

CLAUDE.md is a markdown file placed at the root of your repository. Claude Code Terminal Flicker: NO_FLICKER Config (May 2026)">Claude Code /advisor Troubleshooting: 8 Errors and Fixes (May 2026)">Claude Code /advisor vs claude-code-router: Which Routing Strategy Wins (May 2026)">Claude Code /advisor Recipes: 5 Use Cases with Real Output (May 2026)">Claude Code reads it automatically at the start of every session, giving it essential context about your project: architecture, conventions, commands, and constraints. Think of it as onboarding documentation that both humans and AI read.

The Core Sections Every CLAUDE.md Needs

# CLAUDE.md

## Project Overview
[One paragraph: what this project does, who it's for, current status]

## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.4 (strict mode)
- Styling: Tailwind CSS v4
- Database: PostgreSQL via Prisma ORM
- Auth: Auth.js v5 (NextAuth)
- Testing: Vitest + Playwright
- Deployment: Railway

## Key Commands
```bash
pnpm dev          # Start development server (port 3000)
pnpm build        # Production build
pnpm test         # Run unit tests
pnpm test:e2e     # Run Playwright E2E tests
pnpm db:push      # Push schema changes (dev only)
pnpm db:migrate   # Run migrations (production)
pnpm db:studio    # Open Prisma Studio
```

## Architecture
### Directory Structure
```
src/
  app/           # Next.js App Router pages and layouts
  components/    # Shared UI components
    ui/          # Primitive components (Button, Input, etc.)
    features/    # Feature-specific components
  lib/
    db.ts        # Prisma client singleton
    auth.ts      # Auth.js config
    utils.ts     # Shared utilities
  types/         # TypeScript type definitions
```

## Coding Conventions
- Use named exports, never default exports (except page.tsx files)
- Components use PascalCase, files use kebab-case
- Keep components under 150 lines; extract when longer
- Server Components by default; add "use client" only when needed
- API routes live in app/api/, not pages/api/
- All database queries use the db singleton from lib/db.ts

## Environment Variables
- DATABASE_URL — Postgres connection string
- NEXTAUTH_SECRET — Auth secret (required in production)
- OPENAI_API_KEY — For AI features
- Never commit .env files; .env.example shows required vars

## What To Avoid
- Do not use useEffect for data fetching (use Server Components)
- Do not install lodash (use native ES2024+ methods)
- Do not use any (TypeScript) unless absolutely necessary with comment
- Do not add console.log in committed code

## Testing Conventions
- Unit tests: co-located next to the file being tested
- Component tests: src/tests/components/
- E2E tests: src/tests/e2e/
- Mock external services in tests/mocks/

Advanced Sections Worth Adding

## Current Work in Progress
[Brief note on what's being built — helps AI understand WIP state]

## Known Issues
[Issues the AI should be aware of and not try to "fix"]
- SearchComponent has a known race condition in tests — ignore test failures there

## Performance Requirements
- LCP target: < 2.5s on 4G
- Bundle size: keep initial JS under 150kb

## Data Models
[Brief summary of your main entities — prevents AI from inventing columns]

Keeping CLAUDE.md Updated

Treat CLAUDE.md like a living document. Update it when:

• You add new dependencies
• You establish a new convention
• You find the AI making the same wrong assumption repeatedly

A 30-second CLAUDE.md update saves 5 minutes of AI correction on every future session.