Beginner📝 No Code Required

CLAUDE.md Files

Give Claude persistent memory about your project. Just a text file—anyone can do this.

What Is a CLAUDE.md File?

A CLAUDE.md file is a markdown document at the root of your project that Claude Code reads automatically at the start of every session. It's like a README, but specifically for Claude.

Think of it as onboarding documentation for your AI collaborator. Just like you'd brief a new team member on project context, conventions, and pitfalls—CLAUDE.md does the same for Claude.

Why it matters: Without context, Claude starts every session from zero. With CLAUDE.md, Claude immediately knows your tech stack, conventions, and what to avoid.

Recommended Structure

Keep it under 200 lines. Focus on memory triggers, not verbose explanations. Here's a template that works:

# CLAUDE.md

## Quick Reference
**Stack**: [Your tech stack]
**Critical**: [Most important rule]

## Project Context
[1-2 sentences about what this project does]

## Development Commands
- `npm run dev` - Start development
- `npm run build` - Build for production
- `npm run lint` - Check code quality

## Key Patterns
- [Pattern 1: e.g., "Data lives in /data/*.json"]
- [Pattern 2: e.g., "Never hardcode content in components"]
- [Pattern 3: e.g., "Use Radix UI for complex components"]

## Memory Triggers
- "READ FIRST, EDIT SECOND, ALWAYS"
- "lint before commit"
- [Your project-specific reminders]

## Pitfalls to Avoid
- [Common mistake 1]
- [Common mistake 2]

The key is brevity. Memory triggers should be one-liners that jog memory, not paragraphs that explain everything.

Real Example: This Portfolio Site

Here's a snippet from the CLAUDE.md file for this very website:

# CLAUDE.md

## Quick Reference
**Stack**: Next.js 16 + React 19 + TypeScript + Tailwind + Framer Motion
**Philosophy**: Fitzgerald Principle (opposing forces in productive tension)
**Path Alias**: `@/*` → root directory
**Critical**: Always run `npm run pre-deploy` before committing

## Voice Guidelines
- **Humble explorer**: "Still figuring it out", "happy to share"
- **Direct but warm**: Clear insights without aggressive claims
- **Lead with contrarian insights**: "Most people use AI to do more..."

## Memory Triggers
- "lint before commit - no unescaped entities"
- "Complex UI positioning = Radix first, custom never"
- "READ FIRST, EDIT SECOND, ALWAYS"

Notice how each section is scannable. Claude can quickly find what it needs without reading paragraphs of explanation.

CLAUDE.md at Different Levels

🌍 Global (~/.claude/CLAUDE.md)

Universal standards that apply to ALL your projects. Git safety, documentation standards, your personal conventions.

Example: "NEVER use git add .", "Always check for existing files before creating new ones"

📁 Directory (CODE/CLAUDE.md)

Workspace-level context. If you organize projects in folders, this provides shared context.

Example: "Foundation projects are long-term strategic initiatives"

📦 Project (project/CLAUDE.md)

Project-specific context. Tech stack, commands, patterns, pitfalls unique to this codebase.

Example: "Stack: Next.js 16 + React 19", "Run npm run pre-deploy before commits"

Claude reads all levels, with more specific files taking precedence. Your project CLAUDE.md inherits from global, but can override or extend as needed.

Best Practices

✓ Do's

  • •Keep under 200 lines
  • •Use memory triggers (1-liners)
  • •Include critical commands
  • •Document pitfalls to avoid
  • •Update when patterns change

✗ Don'ts

  • •Don't write paragraphs of explanation
  • •Don't duplicate README content
  • •Don't include sensitive data
  • •Don't let it grow beyond 300 lines
  • •Don't forget @imports for details

Get Started in 5 Minutes

  1. 1.
    Create the file

    Create a file called CLAUDE.md at your project root.

  2. 2.
    Add the basics

    Start with: tech stack, main commands, and one memory trigger.

  3. 3.
    Start a Claude Code session

    Claude will automatically read your CLAUDE.md and apply the context.

  4. 4.
    Iterate

    When you notice Claude making the same mistakes, add a memory trigger. When patterns emerge, document them.

← Context EngineeringNext: Skills →