Writing CLAUDE.md Files

Overview

CLAUDE.md files provide context at different scopes. They follow hierarchical inheritance: global -> project -> folder.

When to Create

Create CLAUDE.md when:

• Project has specific conventions
• Folder has specialized context
• Team patterns need documentation
• Repeated instructions should be automated

Levels:

• ~/.claude/CLAUDE.md - Global (all projects)
• project/CLAUDE.md - Project-level
• project/folder/CLAUDE.md - Folder-specific

Structure Template

# [Project/Folder Name]

## Overview
[Brief description of scope]

## Key Conventions
[Most important rules - loaded every session]

## File Patterns
[Naming, organization, structure]

## Common Tasks
[Frequent operations with guidance]

## Dependencies
[Key libraries, versions, integrations]

## Anti-Patterns
[What to avoid in this context]

Quality Checklist

• Scope clearly defined (global/project/folder)
• Under 500 tokens for always-loaded sections
• Most critical rules first (may be truncated)
• Folder detection patterns if folder-specific
• No duplication of parent-level content
• Anti-patterns documented
• Tested with real prompts

Inheritance Rules

Global CLAUDE.md (always loaded)
    |
    v
Project CLAUDE.md (loaded in project)
    |
    v
Folder CLAUDE.md (loaded in folder context)

Child overrides parent for conflicting rules. Child extends parent for non-conflicting rules.

Token Budget Guidelines

Tips:

• Lead with most critical content
• Use bullet points over prose
• Reference skills instead of duplicating
• Move verbose content to referenced files

Examples

Good Project CLAUDE.md:

# MyApp

## Key Conventions
- TypeScript strict mode
- React Server Components by default
- Supabase for backend

## File Patterns
- Components: src/components/{name}/{name}.tsx
- Server actions: src/actions/{domain}.ts
- Database: supabase/migrations/*.sql

## Common Tasks
- New component: Use shadcn/ui, check existing patterns
- Database change: Create migration, test locally first

## Anti-Patterns
- No client-side data fetching (use RSC)
- No raw SQL (use Supabase client)

Bad CLAUDE.md:

# Instructions

This is a project. It uses various technologies.
Please be careful and write good code.
Follow best practices and industry standards.

(Vague, no actionable content, wastes tokens)

Common Mistakes