Claude Code Research

CLAUDE.md Configuration Best Practices

6 min read

CLAUDE.md Configuration Best Practices

Overview

CLAUDE.md is Claude Code’s memory management system that provides persistent context across coding sessions. This comprehensive guide covers best practices, patterns, and real-world examples for TypeScript developers.

What is CLAUDE.md

CLAUDE.md serves as:

  • 🧠 Persistent Memory: Context that persists across Claude Code sessions
  • 📋 Project Documentation: Centralized place for project-specific instructions
  • 🤝 Team Knowledge Base: Shared conventions and standards
  • 🛠️ Workflow Automation: Custom commands and patterns

Key Features

  • Automatically loaded into context when Claude Code starts
  • Supports hierarchical loading from multiple locations
  • Enables import syntax for modular configuration
  • Quick editing with # key during conversations

File Locations and Hierarchy

Loading Order (All are loaded)

~/.claude/CLAUDE.md         # Global personal preferences
./CLAUDE.md                 # Project team standards
./CLAUDE.local.md          # Project personal preferences (gitignored)
../CLAUDE.md               # Parent directory (for monorepos)
../../CLAUDE.md            # Continues up to root

Best Practice Structure

project/
├── CLAUDE.md              # Team standards (commit to git)
├── CLAUDE.local.md        # Personal overrides (gitignore)
├── .claude/
│   └── commands/          # Custom slash commands
├── docs/
│   ├── api-guidelines.md  # Imported by CLAUDE.md
│   └── testing-rules.md   # Imported by CLAUDE.md
└── packages/
    └── api/
        └── CLAUDE.md      # Package-specific rules

Syntax and Formatting

Import Syntax

# Import project files
@README.md                  # Relative import
@./docs/guidelines.md      # Explicit relative
@package.json              # Common project files
 
# Import from home directory
@~/.claude/typescript.md   # Personal TypeScript rules
 
# Import from absolute paths
@/Users/me/templates/react.md

Key Restrictions

  • Maximum import depth: 5 levels
  • Imports not evaluated in code blocks
  • No dynamic content evaluation
  • Files must be accessible at runtime

Best Practices

1. Be Concise and Specific

# ❌ Bad: Verbose
When working with components, please ensure that you follow
the React best practices including proper prop typing...
 
# ✅ Good: Concise
Components: FC types, explicit props, no any

2. Use Structured Format

# Commands
- dev: npm run dev
- test: npm test --watch
- build: npm run build && npm run typecheck
 
# Architecture
- /api: Express endpoints, Zod validation
- /app: Next.js App Router, RSC
- /lib: Shared utilities, pure functions
 
# Rules
- No any types
- Explicit return types
- 100% test coverage

3. Include Why, Not Just What

# API Design
- RESTful routes (team standard since 2023)
- camelCase responses (frontend convention)
- ISO 8601 dates (parsing consistency)

4. Leverage Quick Updates

  • Press # during conversation to add learnings
  • Creates living documentation
  • Review and refine periodically

TypeScript Patterns

Basic TypeScript Project

# TypeScript Config
- strict: true
- target: ES2022
- moduleResolution: bundler
 
# Type Patterns
- Prefer interfaces for objects
- Use type for unions/aliases
- Explicit return types required
- No implicit any
 
# Import Convention
import type { User } from '@/types'
import { z } from 'zod'

React + TypeScript

# Component Rules
- FC for components with children
- Explicit prop interfaces
- No default exports
- Co-locate styles and tests
 
# State Management
- Zustand for global state
- React Query for server state
- Zod for runtime validation
 
# Example Pattern
interface ButtonProps {
  variant: 'primary' | 'secondary'
  onClick: () => void
}

Full-Stack TypeScript

# Shared Types
- /shared/types: Common interfaces
- tRPC for type-safe APIs
- Prisma for database types
 
# Validation
- Zod schemas in /shared/schemas
- Validate at boundaries
- Parse, don't validate
 
# Testing
- Vitest for unit tests
- Playwright for E2E
- MSW for API mocking

Workshop Examples

Exercise 1: Starter CLAUDE.md

Create a CLAUDE.md for a new React + TypeScript project:

# Project: Todo App
Tech: React 18, TypeScript 5.2, Vite
 
# Setup
- npm install
- npm run dev
 
# Structure
- /components: UI components
- /hooks: Custom React hooks
- /types: TypeScript interfaces
 
# TODO: Add your team's conventions below

Exercise 2: Evolving Documentation

Start with basic, then add as you code:

# Initial
- TypeScript strict mode
- React functional components
 
# After Session 1 (press # to add)
- Use Vitest for testing
- Mock API with MSW
- Button component needs aria-label
 
# After Session 2
- Zustand store in /store
- API client uses Axios
- Error boundaries required

Exercise 3: Team Collaboration

# Team CLAUDE.md (git)
@./docs/api-standards.md
@./docs/testing-requirements.md
 
# Code Review Checklist
- [ ] TypeScript strict passes
- [ ] Tests written and passing
- [ ] API documented in OpenAPI
 
# Personal CLAUDE.local.md (gitignored)
- Prefer npm over yarn
- Use VSCode format on save
- Run tests before commit

Advanced Patterns

Monorepo Configuration

# Root CLAUDE.md
- Turborepo monorepo
- Shared packages in /packages
- Apps in /apps
 
# Import package configs
@./packages/ui/CLAUDE.md
@./packages/api/CLAUDE.md
@./apps/web/CLAUDE.md

Performance Optimization

# Context Management
- Use /compact for long sessions
- Clear context with /clear
- Focus on current task
 
# Token Optimization
- Bullet points over paragraphs
- No redundant information
- Import only needed files

Custom Commands

Create .claude/commands/component.md:

Create a new React component with:
- TypeScript interface
- Storybook story
- Unit test
- CSS module
 
Component name: $ARGUMENTS

Usage: /component Button

Common Mistakes

1. Over-Documentation

# ❌ Bad
React is a JavaScript library for building user interfaces.
It was created by Facebook and uses a component-based...
 
# ✅ Good
React 18, functional components only

2. Outdated Information

# ❌ Bad
- Uses webpack 4 (actually upgraded to Vite)
- Class components preferred (team moved to FC)
 
# ✅ Good
- Vite 5.0 (migrated 2024-01)
- FC only, no class components

3. Missing Context

# ❌ Bad
Use the standard testing setup
 
# ✅ Good
Testing: Vitest + React Testing Library + MSW
Setup: npm test, *.test.tsx adjacent to source

4. Token Waste

# ❌ Bad
Please ensure that when you're writing code, you follow
our team's established patterns for error handling...
 
# ✅ Good
Errors: Try-catch at boundaries, log to Sentry, user-friendly messages

Integration Examples

With CI/CD

# GitHub Actions
- PR checks: lint, typecheck, test
- Main deploys to staging
- Tags deploy to production
 
# Pre-commit
- Prettier formatting
- ESLint fixing
- Type checking

With Development Tools

# VSCode
- Settings in .vscode/
- Recommended extensions
- Format on save enabled
 
# Debug Config
- Chrome debugger configured
- Jest test debugging ready
- Node debugging for API

Quick Reference Card

Essential CLAUDE.md Template

# Tech Stack
[Your stack here]
 
# Commands
- dev: [start command]
- test: [test command]
- build: [build command]
 
# Structure
- /src: [description]
- /tests: [description]
 
# Code Style
- [Key rule 1]
- [Key rule 2]
- [Key rule 3]
 
# Patterns
- [Pattern 1]
- [Pattern 2]

Keyboard Shortcuts

  • # - Quick add to CLAUDE.md
  • /memory - View loaded memory
  • /compact - Compress context
  • /clear - Clear context

Resources

Workshop Takeaways

  1. Start Simple: Begin with minimal CLAUDE.md, expand as needed
  2. Living Document: Use # key to capture learnings
  3. Team Asset: CLAUDE.md is shared knowledge, keep it updated
  4. Token Aware: Every character counts, be concise
  5. Project Specific: Focus on what’s unique to your project

Remember: CLAUDE.md is prepended to every prompt. Write for Claude, not humans. Be concise, specific, and actionable.

Graph View

Backlinks