claude-md-creator

# CLAUDE.md Creator

Create, validate, and maintain CLAUDE.md files with intelligent project detection.

## Workflow Decision Tree

```
                    User Request
                        │
            ┌───────────┴───────────┐
            │   What's needed?      │
            └───────────┬───────────┘
         ┌──────────────┼──────────────┐
         │              │              │
    Create new    Update existing   Validate/Fix
         │              │              │
    ┌────┴────┐    ┌────┴────┐    ┌───┴────┐
    │         │    │         │    │        │
  Which      Detect   Merge    Auto-fix   Auto-fix
  type?      context  changes  issues    issues
    │         │        │        │         │
  Detect    Project   Ask      Run       Run
  context    type     user     fix       fix
    │         │      changes   script    script
    └────┬────┘       │        │         │
         │           │        │         │
    Generate    Generate     Validate   Validate
    content     content      output     output
         │           │        │         │
         └───────────┴────────┴─────────┘
                       │
                  Write to
                  file
```

## Quick Start

| Task | Command |
|------|---------|
| Create project CLAUDE.md | `scripts/generate-claude-md.py --type project` |
| Update existing file | `scripts/update-claude-md.py <path>` |
| Validate file | `scripts/validate-claude-md.py <path>` |
| Auto-fix issues | `scripts/auto-fix-claude-md.py <path>` |
| Detect context | `scripts/detect-claude-type.py` |

## Step 1: Determine CLAUDE.md Type

**Script:** `scripts/detect-claude-type.py`

**Detection Logic:**

| Context | Path | Size Target | When to Use |
|---------|------|-------------|-------------|
| Global | `~/.claude/CLAUDE.md` | 50-150 lines | Personal preferences across all projects |
| Project | `.claude/CLAUDE.md` | 100-300 lines | Team instructions for this project |
| Local | `CLAUDE.local.md` | <50 lines | Personal overrides for this project |
| Rules | `.claude/rules/*.md` | 20-100 each | Modular topics by subject |

## Step 2: Detect Project Type

**Script:** `scripts/detect-project.py`

Scans for project markers to generate smart defaults:

| Marker | Language | Framework | Template Used |
|--------|----------|-----------|---------------|
| `package.json` + "next" | TypeScript | Next.js | `nodejs.md` |
| `package.json` + "react" + "vite" | TypeScript | Vite React | `nodejs.md` |
| `requirements.txt` + "fastapi" | Python | FastAPI | `python.md` |
| `requirements.txt` + "django" | Python | Django | `python.md` |
| `Cargo.toml` | Rust | - | `rust.md` |
| `go.mod` | Go | - | `go.md` |
| None detected | - | - | `general.md` |

## Step 3: Generate CLAUDE.md

**Script:** `scripts/generate-claude-md.py`

**Template Selection:**
```
Base template (assets/*.template.md)
    +
Language template (assets/framework-templates/*.md)
    +
Project-specific data (detected)
    =
Final CLAUDE.md
```

## Step 4: Validate Structure

**Script:** `scripts/validate-claude-md.py`

**Checks Performed:**

| Category | Check | Error Level |
|----------|-------|-------------|
| Frontmatter | Valid YAML fence | ❌ Error |
| Frontmatter | Required fields | ❌ Error |
| Structure | Section headers | ⚠️ Warning |
| Best practices | Line count | ⚠️ Warning |
| Best practices | Table format | ⚠️ Warning |
| Content | Command validity | ⚠️ Warning |
| Content | Path references | ⚠️ Warning |

## Step 5: Auto-Fix Issues

**Script:** `scripts/auto-fix-claude-md.py`

**Auto-Fixes:**

| Issue | Fix | Backup |
|-------|-----|--------|
| Missing frontmatter | Add YAML fence | ✅ Yes |
| Empty sections | Remove or placeholder | ✅ Yes |
| Malformed tables | Convert to proper Markdown | ✅ Yes |
| Extra blank lines | Collapse to 1 line | No |
| Inconsistent headings | Normalize to H2/H3 | ✅ Yes |
| Missing commands | Add from project detection | ✅ Yes |

**Run modes:**
```bash
# Dry run
./auto-fix-claude-md.py --dry-run <path>

# Auto-fix all
./auto-fix-claude-md.py <path>

# Fix specific category
./auto-fix-claude-md.py --category structure <path>
```

## Step 6: Update Existing

**Script:** `scripts/update-claude-md.py`

**Merge Strategy:**
1. Read existing CLAUDE.md
2. Detect project changes
3. Ask user what to update
4. Preserve custom sections
5. Write updated file

## Best Practices

| Principle | Target |
|-----------|--------|
| **Tables > Prose** | Use tables for commands, configs |
| **Specific commands** | Extract real commands from package.json |
| **Line targets** | Global: 50-150, Project: 100-300, Local: <50, Rules: 20-100 |
| **Progressive disclosure** | Quick start → detailed → references |

## Resources

### scripts/

| Script | Purpose | When to Use |
|--------|---------|-------------|
| `detect-claude-type.py` | Determine CLAUDE.md type | Auto-detection |
| `detect-project.py` | Scan project markers | Before generation |
| `generate-claude-md.py` | Create from templates | New file creation |
| `validate-claude-md.py` | Check structure | After edits |
| `auto-fix-claude-md.py` | Fix issues | Validation fails |
| `update-claude-md.py` | Update existing | Project changes |

### references/

| File | Load When |
|------|-----------|
| `best-practices.md` | Writing content |
| `validation-rules.md` | Understanding errors |
| `project-detection.md` | Extending detection |
| `examples/` | Real-world patterns |

### assets/

| File | Purpose |
|------|---------|
| `global.template.md` | Personal preferences |
| `project.template.md` | Team instructions |
| `local.template.md` | Personal overrides |
| `rule.template.md` | Modular topics |
| `framework-templates/*.md` | Language/framework additions |