Best Practices

Knowledge

What Belongs in CLAUDE.md

A good CLAUDE.md contains exactly the information that Claude cannot infer from the code itself. Think of it like a briefing for an experienced developer who is new to the team: You do not explain what a for loop is, but you explain the quirks of your project.

Bash commands that Claude cannot guess:

## Commands
npm run dev          # Dev server (port 3000)
npm run build        # Production build (standalone)
npm run db:migrate   # Apply Prisma migrations
npm run seed         # Load test data

Code style rules that deviate from defaults:

## Code Style
- No semicolons (Prettier config)
- Single quotes instead of double quotes
- Max 100 characters per line
- Imports sorted: external first, then internal with @/ alias

Test instructions and preferred runners:

## Tests
- Unit tests: `vitest run`
- E2E tests: `playwright test`
- Before every commit: `npm run typecheck && npm run test`
- Snapshot tests only for UI components, never for logic

Repository etiquette:

## Git Conventions
- Branch naming: feature/TICKET-123-short-description
- Conventional Commits: feat:, fix:, chore:, docs:
- PRs always against `develop` branch, never directly against `main`
- Squash merge preferred

Architecture decisions:

## Architecture
- App Router with [locale] segment (de/en)
- Zustand for client state, no Redux
- MDX for content, not Markdown
- New components MUST be registered in two files:
  1. src/mdx-components.tsx
  2. src/app/.../page.tsx mdxComponents

Understanding

What Does NOT Belong in CLAUDE.md

Just as important as the content is what you leave out. A CLAUDE.md that is too long gets increasingly ignored by Claude -- similar to how people skim emails that are too long.

What Claude can infer from the code itself:

• The project's programming language
• The directory structure
• Which dependencies are installed
• The syntax of the frameworks used

Standard language conventions:

• "Variables should have descriptive names" -- Claude knows that
• "Use async/await instead of callbacks" -- Standard in modern JavaScript
• "Write types for function parameters" -- TypeScript standard

Long API documentation:

# Bad: Entire API docs copied
## User Endpoint
POST /api/users - Creates a user
  Body: { name: string, email: string, ... }
  Response: { id: number, ... }
  ...50 more lines...

# Better: Link to docs
## API
See @docs/api-reference.md or https://api.example.com/docs

Frequently changing information:

• Current ticket numbers
• Sprint goals
• Temporary workarounds (better as code comments)

Obvious things:

• "Write clean code"
• "Test your changes"
• "Use meaningful variable names"

Applying

## Commands
npm run dev    # Dev server
npm run build  # Production build
npm run lint   # Linting

The 200-Line Target

Keep each individual CLAUDE.md file under 200 lines. This is not a hard limit but a rule of thumb for maximum effectiveness. With longer files, the following happens:

1. Claude prioritizes rules at the beginning of the file more strongly
2. Rules at the end are sometimes overlooked
3. The context budget is unnecessarily burdened

Prune regularly: Review your CLAUDE.md every few weeks. Remove rules that Claude follows anyway (because they are standard) and update outdated information.

Pro Tip: Interactive Init Flow

The standard /init command analyzes your project and generates a CLAUDE.md. For an even more detailed, interactive process, you can set the environment variable:

CLAUDE_CODE_NEW_INIT=true claude

This makes Claude ask you targeted questions about your project and creates a tailored CLAUDE.md based on your answers.