Claude Md

Claude MD

Complete CLAUDE.md management: Audit, Review, Improve, Refactor, Update, and Generate. Core insight: rules with reasoning outperform bare rules. Models generalize from "why" explanations.

Quick Reference

Mode Sequencing

Common workflow combinations:

Generate reuses Phase 1 discovery when Audit already ran in the same session.

Workflow Overview

Phase 1: Discovery

Find all CLAUDE.md files in the repository:

find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

File Types & Locations:

Note: Claude auto-discovers CLAUDE.md files in parent directories, making monorepo setups work automatically.

Phase 2: Quality Assessment

For each CLAUDE.md file, evaluate against the 100-point rubric.

Six Categories (100 points total):

Quality Grades: A (90-100), B (70-89), C (50-69), D (30-49), F (0-29).

See references/quality-criteria.md for the full rubric, sub-criteria point breakdown, and bad/good examples.

## CLAUDE.md Audit Summary

- Files found: 4
- Average score: 72/100 (Grade B)
- Files needing update: 2

| File | Score | Grade | Key Issue |
|------|-------|-------|-----------|
| ./CLAUDE.md | 88/100 | B | Missing gotchas section |
| .claude/rules/coding.md | 91/100 | A | No issues |
| packages/api/CLAUDE.md | 54/100 | C | No commands, vague patterns |
| packages/shared/CLAUDE.md | 56/100 | C | Rules lack reasoning |

Rule Quality Dimensions (for Review mode): 6 dimensions scored 0-3 — Reasoning, Specificity, Positive framing, Examples, Structure, Conflicts. Only rules/patterns/conventions get scored; factual sections (Context, Key Files, Architecture, Commands) are excluded. Full scoring table and "what needs reasoning vs what doesn't" examples in references/quality-criteria.md.

Phase 3: Quality Report Output

Output the quality report before making any updates.

Report Format:

Summary

• Files found: X | Average score: X/100 | Files needing update: X

File-by-File Assessment

1. ./CLAUDE.md (Project Root) — Score: XX/100 (Grade: X)

Issues: [list specific problems] Recommended additions: [list what should be added]

</example>

### Phase 4: Issue Detection (Review Mode)

**Check rules and patterns for:** (not factual context sections)

| Issue Type | Detection | Example Problem | Applies To |
|------------|-----------|-----------------|------------|
| **Missing reasoning** | No "why", "because", explanation | "Never use any" (why?) | Rules, Patterns |
| **Vague instruction** | Not actionable, no concrete guidance | "Write clean code" | Rules, Patterns |
| **Negative-only framing** | "Don't", "Never", "Avoid" without positive alternative | "Don't hardcode URLs" | Rules only |
| **No examples** | Abstract rule without concrete illustration | Complex patterns need examples | Complex rules |
| **Conflicts** | Two rules that contradict | "Use Jest" + "Use Vitest" | All |
| **Redundant** | Duplicates another rule | Same instruction in two places | All |
| **Obvious** | Model does this without instruction | "Use correct syntax" | Rules |
| **Stale commands** | Build commands that no longer work | Outdated paths or scripts | Commands |
| **Missing dependencies** | Required tools not mentioned | Setup requirements omitted | Environment |

**Do NOT flag as issues:**
- Context sections without "why" (factual descriptions don't need reasoning)
- Key Files without explanations (file path + purpose is sufficient)
- Architecture sections without justification (structure is factual)

### Phase 5: Targeted Updates (Improve Mode)

After outputting the quality report, ask user for confirmation before updating.

**Update Guidelines:**

| Do | Skip |
|----|------|
| Propose discovered commands, gotchas, package relationships, working test approaches, config quirks | Restate what's obvious from code, generic best practices, one-off fixes, verbose explanations |

For each change, show: target file, the diff or quoted block, and a brief "why". See [references/update-guidelines.md](references/update-guidelines.md) for the full add-vs-skip heuristics.

**Diff Format:**

<example>
```markdown
### Update: ./CLAUDE.md

**Why:** Build command was missing, causing confusion about how to run the project.

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # Start development server on port 3000
+ ```

</example>

### Phase 6: Refactoring (Refactor Mode)

For bloated files, restructure using progressive disclosure.

**Triage Assessment:**

| Signal | Score |
|--------|-------|
| Already uses `.claude/rules/` structure | +2 |
| Has clear hierarchy (headers, tables) | +1 |
| Contains reasoning ("why" explanations) | +1 |
| Rules are actionable and specific | +1 |
| Under 200 lines with dense content | +1 |
| Over 300 lines | -1 |
| Wall-of-text without structure | -2 |
| Contains contradictions | -2 |
| Mix of vague and specific rules | -1 |

| Score | Action |
|-------|--------|
| 4+ | **Skip** — already well-organized |
| 2-3 | **Light** — extract verbose sections |
| 0-1 | **Standard** — full refactoring |
| Negative | **Deep** — significant restructuring |

<example>
**Refactor triage output:**

```markdown
## Triage: ./CLAUDE.md (380 lines)

| Signal | Score |
|--------|-------|
| Uses `.claude/rules/` | 0 |
| Clear hierarchy | +1 |
| Has reasoning | 0 |
| Actionable rules | +1 |
| Length | -1 (>300) |
| Wall-of-text | -2 |

**Total: -1 → Decision: Standard refactoring**

Plan: Extract coding rules to `.claude/rules/coding.md`, add reasoning to bare directives, move testing patterns to `.claude/rules/testing.md`.

Keep in root (high-value, frequently referenced):

Extract to .claude/rules/ (detailed, topic-specific):

• Detailed language conventions with examples
• Extensive testing patterns
• Framework-specific guidance
• Comprehensive workflow documentation
• Reference tables and checklists

Output structure:

project-root/
├── CLAUDE.md                     # High-value content with @references
└── .claude/
    ├── rules/                    # Auto-loaded by Claude Code
    │   ├── coding.md
    │   ├── testing.md
    │   ├── workflow.md
    │   └── safety.md
    └── reference/                # NOT auto-loaded (search-triggered)
        └── patterns.md

Phase 7: Apply Updates

After user approval, apply changes using the Edit tool. Preserve existing content structure.

Mode: Update (Sync CLAUDE.md with Codebase)

Triggers: "Update CLAUDE.md", "Sync my rules", "Init project", "Refresh project context"

Scans the codebase and updates CLAUDE.md to reflect the current project state. Creates a CLAUDE.md from scratch if none exists. Unlike Improve (which fixes quality issues), Update detects drift between the documented state and the actual codebase.

Key principle: Update adds and corrects factual content (commands, structure, files). It never removes or rewrites user-authored rules, reasoning, or principles unless they reference things that no longer exist.

See references/update-workflow.md for the full scanning algorithm, detection heuristics, and framework-specific patterns.

## CLAUDE.md Update Preview

**Codebase scan results:** Node.js project, pnpm, Next.js 15, TypeScript

### Additions (new sections)
+ ## Commands
+ | `pnpm dev` | Start dev server |
+ | `pnpm build` | Production build |
+ | `pnpm test` | Run vitest |
+ | `pnpm lint` | ESLint check |

+ ## Architecture
+ src/app/        # Next.js app router pages
+ src/lib/        # Shared utilities
+ src/components/ # React components

### Updates (changed content)
~ ## Key Files
~ - `src/lib/db.ts` → renamed to `src/lib/database.ts`
~ - Removed reference to deleted `src/utils/legacy.ts`

### No changes
= ## Hard Rules (unchanged, user-authored)
= ## Core Principles (unchanged, user-authored)

Apply these changes? [All / Select / Cancel]

Mode: Generate (Create Subdirectory Context)

Triggers: "Generate subdirectory context", "Create CLAUDE.md for packages", "Add directory context files"

Workflow: Scan directories, score by "needs context" heuristics, generate minimal CLAUDE.md files for high-value directories, get user approval before creating any files.

See references/generation-workflow.md for the full scoring algorithm, extraction heuristics, and framework-specific guidance.

## Proposed Subdirectory CLAUDE.md Files

### 1. src/api/CLAUDE.md (Score: 7)
**Reason:** 23 files, has index.ts, API domain

**Content:**
# API Layer

@../CLAUDE.md

## Context
Express routes with Zod validation. All routes require auth middleware.

## Key Files
- `index.ts` - Route registration
- `middleware/auth.ts` - JWT validation

## Patterns
- One route file per resource — keeps routing predictable
- Validation schemas co-located with routes — easier to maintain

## Gotchas
- Rate limiting applies per-user, not per-IP

References