CLAUDE.md Best Practices

What to include

An effective CLAUDE.md contains three essential blocks: the tech stack, build/test commands, and critical conventions. Anything Claude can infer from the code itself (folder structure, detected framework, package manager) does not need to be documented.

## Stack
Next.js 14, TypeScript, PostgreSQL/Prisma, pnpm

## Commands
- `pnpm dev`   — start the server
- `pnpm test`  — run tests
- `pnpm build` — production build

## Critical conventions
- Always pnpm, never npm or yarn
- Functional components only
- kebab-case files (my-component.tsx)

What NOT to include

Recommended size

Keep CLAUDE.md between 4 and 8 KB total (all levels combined). Files exceeding 16K tokens degrade model consistency. Boris Cherny (creator of Claude Code) maintains a 2.5K-token CLAUDE.md for his team, capturing conventions built up over months of real usage.

Practical rule: if Claude makes the same mistake twice, add the rule. Do not document everything preemptively.

Hierarchical structure

~/.claude/CLAUDE.md            (global, all projects)
/project/CLAUDE.md             (project, committed)
/project/.claude/CLAUDE.md     (local, gitignore)

In a monorepo, Claude loads the root CLAUDE.md then merges the CLAUDE.md from the active subfolder. Child rules complement parent rules without overriding them.

Explicit imports with @

# In CLAUDE.md
@docs/conventions/coding-standards.md
@docs/conventions/architecture.md

Files imported with @path are loaded on demand, only when referenced. They consume tokens at the moment of use, unlike files in .claude/rules/ which load systematically at startup.

Recommended modular architecture

.claude/
├── CLAUDE.md           (index, < 100 lines)
└── rules/
    ├── testing.md      (coverage thresholds)
    ├── security.md     (security invariants)
    └── api.md          (REST conventions)

CLAUDE.md stays readable at a glance. Detailed rules live in .claude/rules/, loaded automatically every session.