refactor-claude-md

name	refactor-claude-md
description	Modularize large CLAUDE.md files with path-scoped rules and doc extraction

Refactor CLAUDE.md

You are helping refactor a CLAUDE.md file to reduce its size while preserving guidance through dedicated documentation files and path-scoped rules.

Process

1. Read and analyze the current CLAUDE.md file in its entirety

2. Identify extraction candidates -- sections that are:

   • Cross-cutting patterns (not core setup/architecture)
   • Specific to certain file types or components
   • Large sections with detailed patterns
   • Content that would benefit from contextual loading

3. For each candidate section, recommend:

   • Doc name: What to call the extracted file in docs/
   • Content scope: What to include in the doc
   • Path-scoped rule: Glob patterns that should trigger loading this doc
   • Replacement text: Brief reference to keep in CLAUDE.md

4. Suggest documentation table structure:

   • Recommend which docs should be in the main reference table
   • Provide detailed descriptions for the "Description" column
   • Provide specific triggers for the "Read when..." column

5. Create the files in this order:

   • Extract content to docs/[NAME].md
   • Create .claude/rules/[name].md with appropriate globs and @imports
   • Update CLAUDE.md to replace extracted content with brief reference
   • Update the Documentation Reference table if it exists

6. For path-scoped rules, use this format:

   ---
   globs:
     - "pattern1/**/*"
     - "pattern2/**/*"
   imports:
     - docs/DOC_NAME.md
   ---
   
   Brief reminder text with 2-3 key points referencing the imported doc.
   

Key Principles

• Only extract sections that are specific to certain contexts (not universal patterns)
• Preserve critical info in CLAUDE.md (security rules, setup, architecture overview)
• Use meaningful glob patterns that accurately capture when guidance is needed
• Keep replacements brief -- just enough to know where to look
• Documentation table entries should have 2-3 sentence descriptions and specific triggers

Good Extraction Candidates

• UI/styling patterns (CSS variables, Tailwind, responsive design, theming)
• State management patterns (Zustand, persistence, migration safety)
• Architecture patterns for specific systems (Tauri IPC, MCP servers, spec compilation)
• Testing patterns (integration tests, Rust tests, Vitest)
• Feature-specific guides (governance panels, agent execution, git context)

Keep in CLAUDE.md

• Critical warnings (security, destructive operations)
• Development setup and commands
• High-level architecture overview
• General development guidelines
• Monorepo structure (crates, packages, apps, tools, specs)
• Orchestrator behavioral rules

After Extraction

1. Show the size reduction (old lines -> new lines, percentage)
2. List all files created
3. Offer to commit the changes

Ask the user which CLAUDE.md file to refactor (default to ./CLAUDE.md if not specified).

$ARGUMENTS