Review & Optimize CLAUDE.md and Rules Files

You are the orchestrator for a comprehensive audit and optimization of the project's Claude instruction files (CLAUDE.md, .claude/rules/, .claude/skills/). This workflow mirrors what an Anthropic Senior AI Engineer would do: research current best practices, audit the codebase against them, then plan and execute improvements.

This command runs in three phases. Each phase builds on the previous one's output. Do not skip phases or reorder steps.

Phase 1: Research Current Best Practices

Spawn a research agent to find the 2026 (latest) guidance on managing Claude instruction files.

Agent prompt:

Research online the 2026 best practices for managing CLAUDE.md files and .claude/rules/ files in Claude Code projects. Find comprehensive information on:

>

1. How to structure CLAUDE.md files effectively (size targets, what to include/exclude) 2. Best practices for .claude/rules/ directory organization 3. Path-scoped rules via paths: YAML frontmatter — patterns and benefits 4. What belongs in CLAUDE.md vs rules files vs skills vs settings vs hooks 5. Performance/context considerations (line counts, attention degradation, token budgets) 6. Community recommendations and lessons learned from real projects 7. Official Anthropic guidance (code.claude.com/docs) 8. Common anti-patterns (priority saturation, overbroad paths, duplicate content, linter-enforceable prose)

>

Search for recent articles, GitHub repos, blog posts, official docs, and community discussions. Return a detailed summary with specific numbers (line limits, recommended file sizes) and sources.

Wait for the research agent to complete before proceeding.

Phase 2: Audit the Codebase

Using the research findings from Phase 1, perform a comprehensive audit of the project's instruction files.

Step 2.1: Inventory all instruction files

1. Glob for all .claude/rules/*.md files
2. Glob for all **/CLAUDE.md files (exclude node_modules/, .claude/worktrees/)
3. Glob for all .claude/skills/*/SKILL.md files
4. Read every file found. For each file, record:

• File path
• Line count
• Whether it has paths: frontmatter (and if so, the paths listed)
• A one-line summary of its content

Step 2.2: Senior AI Engineer Audit

Spawn an audit agent with the full research findings and file inventory.

Agent prompt:

You are an Anthropic Senior AI Engineer who specializes in Claude Code instruction file optimization. You have deep expertise in how Claude processes CLAUDE.md and rules files, attention degradation in large instruction sets, and the path-scoped rules system.

>

Here are the current best practices from recent research: [INSERT Phase 1 research findings]

>

Here is the complete inventory of instruction files in this project: [INSERT file inventory with line counts, path-scoping status, and content summaries]

>

Perform a thorough audit. For each issue found, classify it as: - CRITICAL: Directly hurts instruction adherence (e.g., 2000+ always-on lines, zero path-scoping) - HIGH: Significant waste or confusion (e.g., 200+ line duplicates, overbroad paths like **/*.py) - MEDIUM: Suboptimal but functional (e.g., workflow-as-rule instead of skill, minor duplication) - LOW: Polish (e.g., linter-enforceable prose, verbose formatting)

>

Specifically evaluate: 1. Total always-on load — sum of lines loaded every session regardless of task 2. Path-scoping coverage — which files lack paths, which have overbroad paths 3. Content duplication — same concept explained in multiple files 4. Misplaced content — workflows that should be skills, rules that should be hooks, domain rules in CLAUDE.md 5. File sizes — any file over 200 lines, any CLAUDE.md over the recommended target 6. Stale or contradictory references — cross-references to moved/renamed/deleted files 7. Linter-enforceable rules — rules that pre-commit hooks or CI already catch

>

For each issue, provide: - The specific file(s) affected - Current state (with line counts) - Recommended change - Expected impact (lines saved, files affected)

>

End with a summary table: current always-on load, target always-on load, number of issues by severity.

Wait for the audit agent to complete.

Step 2.3: Present Audit Results

Present the audit findings to the user in a clear summary:

1. Scorecard: Always-on lines (current vs target), path-scoped file count, duplicate content estimate
2. Issues by severity: Count and brief description of each
3. Top 5 highest-impact changes: What would make the biggest difference
4. Proposed changes: Full list of planned modifications

Ask the user: "Here's the audit report. I have [N] improvements planned. Should I proceed with all of them, or would you like to review specific changes first?"

Wait for user confirmation before proceeding to Phase 3.

Phase 3: Execute Improvements

Based on the audit results and user approval, execute the improvements systematically.

Step 3.1: Create task list

Create tasks for each category of improvement using TaskCreate:

1. Add/fix path-scoping — Add paths: frontmatter to unscoped files, fix overbroad paths
2. Convert workflows to skills — Move step-by-step playbooks from rules to .claude/skills/
3. Deduplicate content — Replace repeated content with single-line pointers to the canonical source
4. Split overloaded files — Break files that mix concerns into focused, properly-scoped files
5. Update references — Fix cross-references in CLAUDE.md files to reflect changes
6. Remove mechanical rules — Delete rules that linters/hooks already enforce

Step 3.2: Execute each task

For each task:

1. Mark it in_progress
2. Read every file that will be modified (mandatory before editing)
3. Make the changes using Edit for modifications, Write for new files, Bash rm for deletions
4. Verify no broken references by grepping for old file names
5. Mark the task completed

Key rules during execution:

• Never delete content without relocating it — if removing from one file, ensure it exists in exactly one canonical location
• Pointer format: When replacing duplicated content, use a one-line pointer like: See \security-auth.md\ for the implementation checklist.
• Path-scoping precision: Prefer specific paths (services/api/migrations/**) over broad globs (**/*.py). A rule that triggers on every Python file is effectively always-on.
• Skill format: Skills go in .claude/skills/{name}/SKILL.md with frontmatter: name, description
• Always-on criteria: Only keep a rule always-on if it applies to ALL code regardless of what's being edited (naming conventions, commit format, CI process, core security principles)

Step 3.3: Verify and report

After all tasks are complete:

1. Run a final inventory: list all instruction files with line counts and scoping status
2. Calculate the before/after metrics:

• Always-on load (lines)
• Number of path-scoped files
• Number of skills (on-demand only)
• Estimated duplicate lines removed

1. Present the results table to the user

Important Notes

• This command modifies .claude/rules/, .claude/skills/, and **/CLAUDE.md files. It does NOT modify application code.
• Always read a file before editing it — the Edit tool requires this.
• If the audit reveals zero issues (already optimized), say so and skip Phase 3.
• If the user has specific concerns ("my rules about X aren't being followed"), investigate those first in the audit.