How to Configure CLAUDE.md for Your Project

CLAUDE.md is a powerful configuration file that gives Claude Code persistent memory about your project. Instead of repeating the same context in every conversation, you define your standards, commands, and conventions once, and Claude follows them automatically.

Understanding CLAUDE.md

When you start Claude Code in a project, it automatically loads any CLAUDE.md files it finds. This content becomes part of Claude's system prompt, meaning every conversation starts with this context already loaded.

Key characteristics:

• Persistent context - Instructions carry across all sessions
• Hierarchical loading - Multiple files can be combined
• High instruction adherence - Claude treats these as authoritative rules
• Human-readable format - Standard markdown, easy to maintain

File Locations and Hierarchy

CLAUDE.md files can exist at multiple levels, loaded from least specific to most specific:

Global Configuration

Path: ~/.claude/CLAUDE.md

• Applies to all projects on your machine
• Good for personal coding preferences that apply everywhere
• Not shared with your team

macOS/Linux location:

~/.claude/CLAUDE.md

Windows location:

%USERPROFILE%\.claude\CLAUDE.md

Project-Level Configuration

Path: CLAUDE.md (project root)

• Shared with your team via version control
• Contains project-specific standards and commands
• Most common location for team projects

Personal overrides:

CLAUDE.local.md    # Add to .gitignore for personal settings

Directory-Level Configuration

Path: subdirectory/CLAUDE.md

• Provides context-specific instructions
• Useful for monorepos with different tech stacks per folder
• Claude loads these on-demand when working in those directories

Loading Order Example

For a file at /myproject/frontend/components/Button.tsx:

1. ~/.claude/CLAUDE.md (global)
2. /myproject/CLAUDE.md (project root)
3. /myproject/frontend/CLAUDE.md (subdirectory)
4. /myproject/frontend/components/CLAUDE.md (nested)

More specific files take precedence when instructions conflict.

Creating Your CLAUDE.md

Quick Start with /init

The fastest way to create a CLAUDE.md is using the /init command:

# In your project directory
claude
> /init

Claude analyzes your codebase and generates a starter file based on:

• Package files (package.json, requirements.txt, etc.)
• Existing documentation
• Configuration files
• Code structure and patterns

Important: Treat /init as a starting point. Review and refine the generated file based on your team's actual practices.

Manual Creation

Create a file named CLAUDE.md in your project root:

touch CLAUDE.md

Critical: The filename is case-sensitive. It must be exactly CLAUDE.md (uppercase).

What to Include

Structure your CLAUDE.md around three core areas:

1. WHAT - Project Context

Tell Claude about your technology stack and structure:

# Project Overview

This is a Next.js 15 e-commerce application using TypeScript, Tailwind CSS,
and PostgreSQL. We deploy to Cloudflare Pages with D1 for the database.

## Key Directories

- `app/` - Next.js App Router pages and layouts
- `components/` - React components (ui/ for primitives, features/ for complex)
- `lib/` - Business logic, utilities, and data access
- `db/` - Database schema and migrations

2. WHY - Purpose and Patterns

Explain the reasoning behind your architecture:

## Architecture Decisions

We use server components by default for SEO and performance. Client components
('use client') are only for interactive features requiring hooks or event handlers.

All API routes use Edge runtime for Cloudflare compatibility - never use Node.js
runtime unless explicitly instructed.

3. HOW - Commands and Workflows

Provide the exact commands Claude should use:

## Development Commands

```bash
npm run dev      # Start dev server (http://localhost:3000)
npm run build    # Build for production (ALWAYS run before presenting work)
npm run lint     # Run ESLint
npm run test     # Run test suite

Code Style

• TypeScript strict mode enabled
• Prefer interfaces over types
• Use named exports (not default exports)
• 2-space indentation
• No semicolons (Prettier config)

Testing Requirements

• Write tests for all new features
• Run npm run test before committing
• Minimum 80% coverage for business logic

## Complete Example

Here's a comprehensive CLAUDE.md for a typical web project:

```markdown
# CLAUDE.md

## Project Overview

Next.js 15 SaaS application with TypeScript, Tailwind CSS 4, and Supabase.
Edge runtime required for all API routes (Cloudflare deployment).

## Quick Reference

- **Build**: `npm run build` - Run before presenting any changes
- **Test**: `npm run test` - Required before committing
- **Lint**: `npm run lint` - Auto-fixes most issues

## Key Directories

- `app/` - Next.js App Router (pages, layouts, API routes)
- `components/ui/` - Reusable UI primitives
- `components/features/` - Feature-specific components
- `lib/` - Business logic and utilities
- `lib/data/` - Data access layer
- `db/` - Database schema and migrations

## Code Standards

### TypeScript
- Strict mode enabled
- No `any` - use `unknown` and type guards
- Prefer interfaces for object types
- Use satisfies for type checking without widening

### React
- Server components by default
- Client components only when hooks/interactivity needed
- Colocate related files (component, styles, tests)

### Imports
- Use `@/` path alias for all imports
- Group: external, internal, relative, types

## Self-Verification Workflow

IMPORTANT: Always verify work before presenting.

1. Write code
2. Run `npm run build` - fix any errors
3. Run `npm run lint` - fix any warnings
4. Test in dev server if applicable
5. Only then present the changes

## Gotchas

- Authentication module uses custom retry logic - don't modify without tests
- The `/api/webhook` route has specific header requirements (see comments)
- Never modify files in `/generated/` - these are auto-generated

## Database

Query using Supabase client in `lib/supabase.ts`. Never write raw SQL in
components - always use the data layer functions in `lib/data/`.

Best Practices

Keep It Concise

Every line competes for Claude's attention. Research suggests frontier LLMs can reliably follow 150-200 instructions. Remove anything that doesn't provide genuine value.

# Good - Specific and actionable
Use 2-space indentation. Run `npm run build` before committing.

# Bad - Vague and unnecessary
Please write good code. Try to follow best practices.

Use Progressive Disclosure

Don't dump everything Claude might need. Instead, point to where information lives:

## Additional Context

- API documentation: See `/docs/api.md`
- Component patterns: See `CONTRIBUTING.md`
- Database schema: See `/db/schema.sql`

Emphasize Critical Rules

For rules that must never be broken, use emphasis:

**IMPORTANT**: Never modify the `/migrations/` folder directly.

YOU MUST run tests before committing any database changes.

Add Instructions On-the-Fly

Press # during a Claude Code session to add notes to your CLAUDE.md:

You: # Always use async/await instead of .then() chains

Claude will add this to the appropriate CLAUDE.md file. This is great for documenting discoveries as you code.

Refactor Regularly

CLAUDE.md files grow. Periodically review and clean them:

• Remove outdated instructions
• Consolidate duplicate guidance
• Move detailed docs to separate files
• Keep the main file focused on essentials

Platform-Specific Configuration

macOS

Global configuration path:

~/.claude/CLAUDE.md

Editing global config:

# Using your default editor
open ~/.claude/CLAUDE.md

# Or with VS Code
code ~/.claude/CLAUDE.md

Windows

Global configuration path:

%USERPROFILE%\.claude\CLAUDE.md

Editing in PowerShell:

# Using Notepad
notepad $env:USERPROFILE\.claude\CLAUDE.md

# Or with VS Code
code $env:USERPROFILE\.claude\CLAUDE.md

For WSL users, the Linux path applies within WSL:

~/.claude/CLAUDE.md

Linux

Global configuration path:

~/.claude/CLAUDE.md

Create the directory if needed:

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

Related Configuration

CLAUDE.md works alongside other Claude Code configuration:

Settings Files

~/.claude/settings.json         # Global settings (all projects)
.claude/settings.json           # Project settings (team-shared)
.claude/settings.local.json     # Personal overrides (gitignored)

Settings control permissions, environment variables, and tool behavior.

Custom Commands

Create reusable prompts in .claude/commands/:

<!-- .claude/commands/review.md -->
---
description: Review code for issues
---
Review the current file for:
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing error handling

Invoke with /review in Claude Code.

Skills

For complex, multi-file capabilities, use skills in .claude/skills/:

.claude/skills/
  deploy/
    SKILL.md
    deploy.sh

Skills can be auto-invoked by Claude or manually triggered.

Troubleshooting

CLAUDE.md Not Being Loaded

1. Verify the filename is exactly CLAUDE.md (case-sensitive)
2. Check the file is in the correct location
3. Ensure the file has read permissions
4. Try running /init to regenerate

Instructions Not Being Followed

1. Keep instruction count under 200
2. Make instructions specific and actionable
3. Use emphasis for critical rules
4. Remove conflicting or contradictory guidance
5. Check if context drift occurred (use /clear between distinct tasks)

Team Members Have Different Behavior

1. Check for CLAUDE.local.md files overriding shared settings
2. Verify everyone has the latest CLAUDE.md from version control
3. Ensure global ~/.claude/CLAUDE.md files aren't conflicting

Next Steps

• Install Claude Code CLI if you haven't already
• Read the official Claude Code documentation
• Explore Claude Code best practices from Anthropic
• Check out the Complete Guide to CLAUDE.md for more examples

Need help optimizing your AI development workflow? Inventive HQ helps teams integrate AI coding tools effectively. Contact us for a consultation on Claude Code setup and best practices.