The Complete Guide to Writing CLAUDE.md: Best Practices for Project Configuration

What Is CLAUDE.md?

CLAUDE.md is a context file that helps Claude Code understand your project. Place it at your project root, and Claude Code automatically reads it at the start of every session. A well-written CLAUDE.md can dramatically improve the quality of Claude Code’s responses.

File Locations and Priority

You can place CLAUDE.md files in multiple locations, and all of them are loaded:

~/.claude/CLAUDE.md          # Global settings (shared across all projects)
./CLAUDE.md                   # Project root (shared with the team)
./CLAUDE.local.md             # Local settings (add to .gitignore)
./src/CLAUDE.md               # Subdirectory-level settings

• Global: Your personal coding style preferences
• Project root: Team-shared rules and tech stack
• Local: Personal settings not committed to Git
• Subdirectory: Additional context for specific modules

Starter Template

Here’s a practical CLAUDE.md template:

# Project Overview

E-commerce backend API. Handles order management, inventory, and user authentication.

## Tech Stack

- Language: TypeScript 5.x
- Runtime: Node.js 22
- Framework: Fastify
- DB: PostgreSQL 16 + Prisma ORM
- Testing: Vitest
- CI: GitHub Actions

## Directory Structure

src/
  routes/       # API endpoint definitions
  services/     # Business logic
  repositories/ # Data access layer
  middleware/   # Auth, logging, error handling
  utils/        # Utility functions
  types/        # Type definitions

## Coding Conventions

- Use arrow functions
- Always use try-catch for error handling with custom error classes
- Naming: camelCase (variables/functions), PascalCase (types/classes)
- File names: kebab-case
- Use path alias `@/` instead of relative imports

## Common Commands

- Run tests: `npm test`
- Type check: `npx tsc --noEmit`
- Lint: `npm run lint`
- DB migration: `npx prisma migrate dev`
- Dev server: `npm run dev`

## Important Rules

- Always create a migration after changing prisma/schema.prisma
- Every API endpoint must have a Zod validation schema
- Register new routes in routes/index.ts

Tips for Writing Effective CLAUDE.md Files

1. Keep It Concise

CLAUDE.md consumes context window tokens. Avoid verbose explanations and stick to bullet points.

# Bad example
This project uses TypeScript. TypeScript is a language developed
by Microsoft that adds types to JavaScript...

# Good example
- Language: TypeScript 5.x (strict mode)

2. Document What You Don’t Want

Explicitly listing anti-patterns is surprisingly effective.

## Prohibited

- No `any` types
- No default exports (named exports only)
- No console.log for debugging (use the logger)
- Never delete or skip existing tests

3. Define Workflows

Guide Claude Code on how tasks should be approached.

## Adding a New Feature

1. Create type definitions in `src/types/`
2. Implement the data access layer in `src/repositories/`
3. Implement business logic in `src/services/`
4. Define endpoints in `src/routes/`
5. Write unit tests for each layer
6. Verify all tests pass with `npm test`

4. Capture Tribal Knowledge

Document important information that isn’t written down elsewhere.

## Project-Specific Notes

- `user_id` uses UUID v7 (for time-sortable ordering)
- All price calculations must use `Decimal.js` (to avoid floating-point errors)
- Environment variables are centralized in `src/config.ts` — never access process.env directly

Team Usage

.gitignore Setup

Keep personal settings out of version control:

# .gitignore
CLAUDE.local.md

Include in Code Reviews

Treat CLAUDE.md as an important project document. Include it in PR reviews and keep it up to date as a team.

When to Update CLAUDE.md

• When adding a new library
• When changing coding conventions
• When restructuring directories
• When you notice Claude Code repeatedly making the same mistake

Conclusion

CLAUDE.md turns Claude Code into an expert on your specific project. Start by generating a scaffold with /init, then refine it as you work. Share it with your team so everyone benefits from optimized Claude Code interactions.