MD Tuner

Optimize Claude configuration files for maximum effectiveness within context window constraints.

Analysis Checklist

Evaluate against these criteria:

1. Line Count - Target under 300 lines (ideal: under 100)
2. Universal Applicability - Instructions should apply to most tasks
3. Instruction Density - LLMs follow ~150-200 instructions consistently; Claude Code's system prompt uses ~50
4. Progressive Disclosure - Task-specific content in separate files, referenced from main
5. Emphasis Usage - Critical rules use "IMPORTANT" or "YOU MUST"
6. Content Categories - Covers: commands, core files, style, testing, repo etiquette, environment setup, project quirks

Recommended Content Categories (Anthropic)

A well-structured CLAUDE.md should include:

• Common bash commands with descriptions
• Core files and utility functions
• Code style guidelines (or pointer to linter config)
• Testing instructions
• Repository etiquette (branching, merge strategies)
• Developer environment setup
• Project-specific quirks or warnings
• Domain knowledge to persist across sessions

File Placement Hierarchy

Claude Code supports multiple config locations (loaded in order):

1. ~/.claude/CLAUDE.md - Global, all sessions
2. Repository root CLAUDE.md - Shared via git
3. .claude/CLAUDE.local.md - Personal, gitignored
4. Parent directories in monorepos - Inherited by subdirs
5. Child directories - Loaded on-demand when working there

Recommendation: Use hierarchy strategically. Global for universal prefs, repo-level for project rules, local for personal overrides.

Scoring Criteria

Optimization Workflow

Step 1: Read & Identify Location

Read the target file. Note its placement in the hierarchy (global vs repo vs local).

Step 2: Score Against Criteria

Apply scoring table. Calculate weighted total.

Step 3: Identify Issues

Flag problems:

• Task-specific content that should be in child/separate files
• Code snippets → convert to file:line pointer references
• Vague instructions → make specific with context
• Missing emphasis on critical rules
• Content that duplicates Claude's default behavior
• Untested additions (treat CLAUDE.md like prompt engineering)

Step 4: Recommend Structure

~/.claude/CLAUDE.md              # Universal preferences
project/
├── CLAUDE.md                    # Shared team rules
├── .claude/
│   └── CLAUDE.local.md          # Personal overrides (gitignored)
└── agent_docs/                  # Progressive disclosure
    ├── commands.md
    ├── testing.md
    ├── architecture.md
    └── [domain].md

Step 5: Provide Rewrite

Optimized version should:

• Be concise and human-readable (Anthropic's only format requirement)
• Use emphasis for critical rules: "IMPORTANT:", "YOU MUST"
• Reference external docs instead of inline content
• Remove obvious/default Claude behaviors
• Cover relevant content categories
• Match placement to scope (global vs project vs personal)

Anti-Patterns to Flag

• Extensive content added without testing effectiveness
• Auto-generated /init content kept without curation
• Every possible command listed exhaustively
• Database schemas or API docs inline
• Code examples instead of file references
• Instructions Claude already follows by default
• Vague or generic instructions without specifics
• No emphasis differentiation (everything same priority)

Output Format

## MD Tuner Analysis

**File:** [path]
**Location:** [global/repo/local]
**Lines:** [count] ([status])
**Score:** [X]/100

### Scoring Breakdown
| Criterion | Score |
|-----------|-------|
| ... | ...% |

### Issues Found
1. [Line X: Issue description]
2. ...

### Recommendations
1. [Specific actionable item]
2. ...

### Suggested Structure
[If restructuring needed]

### Optimized Version
[Rewritten config]