CLAUDE.md Guide

Master the CLAUDE.md file format to give Claude perfect context about your projects

title: CLAUDE.md Guide description: Master the CLAUDE.md file format to give Claude perfect context about your projects

The CLAUDE.md file is the primary way to provide Claude Code with context about your project. When you start a session, Claude automatically reads these files to understand your codebase, conventions, and preferences.

Why Use CLAUDE.md?

Without context, Claude has to infer information about your project from the code itself. With a well-crafted CLAUDE.md, you can:

• Reduce repetition - No need to explain your stack every session
• Ensure consistency - Claude follows your conventions automatically
• Speed up workflows - Claude understands your project structure immediately
• Improve accuracy - Better context leads to better suggestions

File Location

Claude Code looks for CLAUDE.md files in several locations:

Precedence: Directory-specific > Project root > Global

Basic Structure

A typical CLAUDE.md includes these sections:

Complete Example

Here's a comprehensive CLAUDE.md for a Next.js project:

Section Deep Dive

Overview Section

Keep it concise but informative:

Tech Stack Section

List versions for accuracy:

Conventions Section

Be specific about patterns:

Directory-Specific Overrides

Create CLAUDE.md files in subdirectories for specialized instructions:

tests/CLAUDE.md

scripts/CLAUDE.md

Tips for Effective CLAUDE.md

1. Update regularly - Keep it in sync with your project
2. Be specific - Vague instructions lead to vague results
3. Include examples - Show don't just tell
4. Document gotchas - Warn about common pitfalls
5. Keep it readable - Use clear headings and formatting

Common Patterns

For APIs

For CLI Tools

For Libraries

Next Steps

• Configure Claude Code settings
• Learn effective prompting
• Set up IDE integration