CLAUDE.md Best Practices

Why CLAUDE.md Matters

The CLAUDE.md file sits at the root of your project and acts as a persistent system prompt for every Claude Code session. It's the single highest-leverage thing you can add to a project.

Without it, Claude infers your stack from file contents. With it, Claude knows your stack, conventions, and preferences from the first message.

The Anatomy of a Good CLAUDE.md

Keep it under 50 lines. Here's the structure:

# Project Name

Brief one-liner about what the project is.

## Tech Stack
- Next.js 14 (App Router, NOT Pages Router)
- TypeScript in strict mode
- Tailwind CSS v4
- SQLite via Prisma

## Conventions
- Components in src/components/ (kebab-case filenames)
- Server components by default, client only when needed
- Named exports, no default exports for components

## Commands
- npm run dev — start dev server (port 3000)
- npm run build — production build
- npm run test — run test suite

## Anti-patterns (avoid)
- Don't use `any` type
- Don't create barrel files (index.ts re-exports)
- Don't add comments explaining obvious code

Tip 1: Be Explicit About Your Stack

Don't say "React" — say "Next.js 14 with App Router." Don't say "CSS" — say "Tailwind CSS v4 with @theme tokens." The more specific, the fewer corrections you'll make.

Tip 2: State the Negative

What Claude should NOT do is often more important than what it should do:

## Don't
- Don't use class components
- Don't add try/catch to every function
- Don't create abstractions for one-time operations

Tip 3: Include File Paths

Tell Claude where things live:

## Key Files
- src/lib/db.ts — database client (import from here, don't create new instances)
- src/lib/auth.ts — auth config and helpers
- src/data/videos.ts — static video data

Tip 4: Document Your Commands

Claude can run shell commands but doesn't know your custom scripts:

## Commands
- npm run dev — start dev server
- npm run build — type-check + build
- npm run db:push — push schema changes
- npm run db:seed — reset and seed database

Tip 5: Keep It Short

Your CLAUDE.md is loaded into context every session. A 500-line document wastes tokens and dilutes signal. Aim for 30-50 lines.

If you need more detail, link to other files:

## Reference
- API patterns: see docs/api-patterns.md
- Component guide: see docs/components.md

Claude reads those on demand without loading them every time.

Updating It

Treat CLAUDE.md like code. When you find yourself correcting Claude on the same thing twice, add it to the file. When a convention changes, update the file. Review it monthly and prune anything that's no longer true.