claude-md

# CLAUDE.md Skill

Create effective CLAUDE.md files that transform Claude Code from a general-purpose assistant into a specialized tool for specific codebases.

## Core Philosophy

CLAUDE.md is Claude Code's "constitution" - it provides persistent context automatically loaded at conversation start. Every token counts because CLAUDE.md competes for context window space with conversation history, file contents, and tool results.

**Golden Rule:** Document what Claude gets wrong, not everything Claude might need. Start small, expand based on friction.

## CLAUDE.md Hierarchy

Claude Code loads CLAUDE.md files from multiple locations (all are merged):

| Location | Purpose | Git Status |
|----------|---------|------------|
| `~/.claude/CLAUDE.md` | Personal preferences across all projects | N/A |
| `repo/CLAUDE.md` | Team-shared project context | Commit |
| `repo/CLAUDE.local.md` | Personal project overrides | .gitignore |
| `repo/subdir/CLAUDE.md` | Subdirectory-specific context (monorepos) | Commit |

## Creation Workflow

### 1. Analyze the Codebase

Before writing, understand what Claude will struggle with:

```bash
# Identify key files and structure
find . -maxdepth 3 -type f -name "*.md" | head -20
ls -la package.json pyproject.toml Makefile 2>/dev/null

# Check for existing documentation
cat README.md 2>/dev/null | head -50

# Identify build/test commands
grep -E "scripts|test|build|dev" package.json 2>/dev/null
```

### 2. Structure Template

Use this proven structure (adapt sections as needed):

```markdown
# CLAUDE.md

[One-line project description]

## Quick Start

```bash
[Package manager] install
[Dev command]
[Test command]
```

## Architecture

[2-3 sentences on structure, key patterns, main technologies]

### Key Directories
- `src/` - [purpose]
- `tests/` - [purpose]

## Code Standards

- [Style rule with example if non-obvious]
- [Critical pattern to follow]
- [Common mistake to avoid → correct approach]

## Critical Rules

**MUST:**
- [Non-negotiable