Claude Md Improver

CLAUDE.md Improver

Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure Claude Code has optimal project context.

This skill can write to CLAUDE.md files. After presenting a quality report and getting user approval, it updates CLAUDE.md files with targeted improvements.

Workflow

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 quality criteria. See references/quality-criteria.md for detailed rubrics.

Quick Assessment Checklist:

Quality Scores:

• A (90-100): Comprehensive, current, actionable
• B (70-89): Good coverage, minor gaps
• C (50-69): Basic info, missing key sections
• D (30-49): Sparse or outdated
• F (0-29): Missing or severely outdated

Phase 3: Quality Report Output

ALWAYS output the quality report BEFORE making any updates.

Format:

## CLAUDE.md Quality Report

### 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)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

#### 2. ./packages/api/CLAUDE.md (Package-specific)
...

Phase 4: Targeted Updates

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

Update Guidelines (Critical):

1. Propose targeted additions only - Focus on genuinely useful info:

• Commands or workflows discovered during analysis
• Gotchas or non-obvious patterns found in code
• Package relationships that weren't clear
• Testing approaches that work
• Configuration quirks

2. Keep it minimal - Avoid:

• Restating what's obvious from the code
• Generic best practices already covered
• One-off fixes unlikely to recur
• Verbose explanations when a one-liner suffices

3. Show diffs - For each change, show:

• Which CLAUDE.md file to update
• The specific addition (as a diff or quoted block)
• Brief explanation of why this helps future sessions

Diff Format:

### Update: ./CLAUDE.md

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

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

Phase 5: Apply Updates

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

Templates

See references/templates.md for CLAUDE.md templates by project type.

Common Issues to Flag

1. Stale commands: Build commands that no longer work 2. Missing dependencies: Required tools not mentioned 3. Outdated architecture: File structure that's changed 4. Missing environment setup: Required env vars or config 5. Broken test commands: Test scripts that have changed 6. Undocumented gotchas: Non-obvious patterns not captured

User Tips to Share

When presenting recommendations, remind users:

• `#` key shortcut: During a Claude session, press # to have Claude auto-incorporate learnings into CLAUDE.md
• Keep it concise: CLAUDE.md should be human-readable; dense is better than verbose
• Actionable commands: All documented commands should be copy-paste ready
• Use `.claude.local.md`: For personal preferences not shared with team (add to .gitignore)
• Global defaults: Put user-wide preferences in ~/.claude/CLAUDE.md

What Makes a Great CLAUDE.md

Key principles:

• Concise and human-readable
• Actionable commands that can be copy-pasted
• Project-specific patterns, not generic advice
• Non-obvious gotchas and warnings

Recommended sections (use only what's relevant):

• Commands (build, test, dev, lint)
• Architecture (directory structure)
• Key Files (entry points, config)
• Code Style (project conventions)
• Environment (required vars, setup)
• Testing (commands, patterns)
• Gotchas (quirks, common mistakes)
• Workflow (when to do what)

Related Skills

• dependency-upgrade: Include dependency hardening policies and lockfile/security workflow guidance when improving repository CLAUDE.md files

CLAUDE.md Quality Criteria

Scoring Rubric

1. Commands/Workflows (20 points)

20 points: All essential commands documented with context

• Build, test, lint, deploy commands present
• Development workflow clear
• Common operations documented

15 points: Most commands present, some missing context

10 points: Basic commands only, no workflow

5 points: Few commands, many missing

0 points: No commands documented

2. Architecture Clarity (20 points)

20 points: Clear codebase map

• Key directories explained
• Module relationships documented
• Entry points identified
• Data flow described where relevant

15 points: Good structure overview, minor gaps

10 points: Basic directory listing only

5 points: Vague or incomplete

0 points: No architecture info

3. Non-Obvious Patterns (15 points)

15 points: Gotchas and quirks captured

• Known issues documented
• Workarounds explained
• Edge cases noted
• "Why we do it this way" for unusual patterns

10 points: Some patterns documented

5 points: Minimal pattern documentation

0 points: No patterns or gotchas

4. Conciseness (15 points)

15 points: Dense, valuable content

• No filler or obvious info
• Each line adds value
• No redundancy with code comments

10 points: Mostly concise, some padding

5 points: Verbose in places

0 points: Mostly filler or restates obvious code

5. Currency (15 points)

15 points: Reflects current codebase

• Commands work as documented
• File references accurate
• Tech stack current

10 points: Mostly current, minor staleness

5 points: Several outdated references

0 points: Severely outdated

6. Actionability (15 points)

15 points: Instructions are executable

• Commands can be copy-pasted
• Steps are concrete
• Paths are real

10 points: Mostly actionable

5 points: Some vague instructions

0 points: Vague or theoretical

Assessment Process

1. Read the CLAUDE.md file completely 2. Cross-reference with actual codebase:

• Run documented commands (mentally or actually)
• Check if referenced files exist
• Verify architecture descriptions

3. Score each criterion 4. Calculate total and assign grade 5. List specific issues found 6. Propose concrete improvements

Red Flags

• Commands that would fail (wrong paths, missing deps)
• References to deleted files/folders
• Outdated tech versions
• Copy-paste from templates without customization
• Generic advice not specific to the project
• "TODO" items never completed
• Duplicate info across multiple CLAUDE.md files

CLAUDE.md Templates

Key Principles

• Concise: Dense, human-readable content; one line per concept when possible
• Actionable: Commands should be copy-paste ready
• Project-specific: Document patterns unique to this project, not generic advice
• Current: All info should reflect actual codebase state

---

Recommended Sections

Use only the sections relevant to the project. Not all sections are needed.

Commands

Document the essential commands for working with the project.

## Commands

| Command | Description |
|---------|-------------|
| `<install command>` | Install dependencies |
| `<dev command>` | Start development server |
| `<build command>` | Production build |
| `<test command>` | Run tests |
| `<lint command>` | Lint/format code |

Architecture

Describe the project structure so Claude understands where things live.

## Architecture

<root>/ <dir>/ # <purpose> <dir>/ # <purpose> <dir>/ # <purpose>

Key Files

List important files that Claude should know about.

## Key Files

- `<path>` - <purpose>
- `<path>` - <purpose>

Code Style

Document project-specific coding conventions.

## Code Style

- <convention>
- <convention>
- <preference over alternative>

Environment

Document required environment variables and setup.

## Environment

Required:
- `<VAR_NAME>` - <purpose>
- `<VAR_NAME>` - <purpose>

Setup:
- <setup step>

Testing

Document testing approach and commands.

## Testing

- `<test command>` - <what it tests>
- <testing convention or pattern>

Gotchas

Document non-obvious patterns, quirks, and warnings.

## Gotchas

- <non-obvious thing that causes issues>
- <ordering dependency or prerequisite>
- <common mistake to avoid>

Workflow

Document development workflow patterns.

## Workflow

- <when to do X>
- <preferred approach for Y>

---

Template: Project Root (Minimal)

# <Project Name>

<One-line description>

## Commands

| Command | Description |
|---------|-------------|
| `<command>` | <description> |

## Architecture

<structure>

## Gotchas

- <gotcha>

---

Template: Project Root (Comprehensive)

# <Project Name>

<One-line description>

## Commands

| Command | Description |
|---------|-------------|
| `<command>` | <description> |

## Architecture

<structure with descriptions>

## Key Files

- `<path>` - <purpose>

## Code Style

- <convention>

## Environment

- `<VAR>` - <purpose>

## Testing

- `<command>` - <scope>

## Gotchas

- <gotcha>

---

Template: Package/Module

For packages within a monorepo or distinct modules.

# <Package Name>

<Purpose of this package>

## Usage

<import/usage example>

## Key Exports

- `<export>` - <purpose>

## Dependencies

- `<dependency>` - <why needed>

## Notes

- <important note>

---

Template: Monorepo Root

# <Monorepo Name>

<Description>

## Packages

| Package | Description | Path |
|---------|-------------|------|
| `<name>` | <purpose> | `<path>` |

## Commands

| Command | Description |
|---------|-------------|
| `<command>` | <description> |

## Cross-Package Patterns

- <shared pattern>
- <generation/sync pattern>

---

Update Principles

When updating any CLAUDE.md:

1. Be specific: Use actual file paths, real commands from this project 2. Be current: Verify info against the actual codebase 3. Be brief: One line per concept when possible 4. Be useful: Would this help a new Claude session understand the project?

CLAUDE.md Update Guidelines

Core Principle

Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.

What TO Add

1. Commands/Workflows Discovered

## Build

`npm run build:prod` - Full production build with optimization
`npm run build:dev` - Fast dev build (no minification)

Why: Saves future sessions from discovering these again.

2. Gotchas and Non-Obvious Patterns

## Gotchas

- Tests must run sequentially (`--runInBand`) due to shared DB state
- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch

Why: Prevents repeating debugging sessions.

3. Package Relationships

## Dependencies

The `auth` module depends on `crypto` being initialized first.
Import order matters in `src/bootstrap.ts`.

Why: Architecture knowledge that isn't obvious from code.

4. Testing Approaches That Worked

## Testing

For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
Mocking: Factory functions in `tests/factories/` (not inline mocks)

Why: Establishes patterns that work.

5. Configuration Quirks

## Config

- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
- Redis connection requires `?family=0` suffix for IPv6

Why: Environment-specific knowledge.

What NOT to Add

1. Obvious Code Info

Bad:

The `UserService` class handles user operations.

The class name already tells us this.

2. Generic Best Practices

Bad:

Always write tests for new features.
Use meaningful variable names.

This is universal advice, not project-specific.

3. One-Off Fixes

Bad:

We fixed a bug in commit abc123 where the login button didn't work.

Won't recur; clutters the file.

4. Verbose Explanations

Bad:

The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
an open standard (RFC 7519) that defines a compact and self-contained
way for securely transmitting information between parties as a JSON
object. In our implementation, we use the HS256 algorithm which...

Good:

Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.

Diff Format for Updates

For each suggested change:

1. Identify the File

File: ./CLAUDE.md
Section: Commands (new section after ## Architecture)

2. Show the Change

 ## Architecture
 ...

+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Dev server with HMR |
+| `npm run build` | Production build |
+| `npm test` | Run test suite |

3. Explain Why

Why this helps: The build commands weren't documented, causing

confusion about how to run the project. This saves future sessions

from needing to inspect package.json.

Validation Checklist

Before finalizing an update, verify:

• [ ] Each addition is project-specific
• [ ] No generic advice or obvious info
• [ ] Commands are tested and work
• [ ] File paths are accurate
• [ ] Would a new Claude session find this helpful?
• [ ] Is this the most concise way to express the info?