/refactor-claude-md

description: Refactor CLAUDE.md by extracting sections to dedicated docs with path-scoped rules

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 a `paths:` frontmatter and a link to the doc
• Update CLAUDE.md to replace extracted content with a one-line rule plus the link
• Update the "Read before working in an area" table if it exists

6. **For path-scoped rules**, use this format. Claude Code scopes rules with `paths:`; `globs:` and `imports:` are not recognized and the rule would load unconditionally with no doc attached.

   ---
   paths:
     - "pattern1/**"
     - "pattern2/**/*.tsx"
   ---

   Read [docs/DOC_NAME.md](../../docs/DOC_NAME.md) before changing these files. Key points:

   - two or three one-line points

Key Principles

• **Only extract** sections that are specific to certain contexts (not universal patterns)
• **Preserve critical info** in CLAUDE.md (database 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)
• State management patterns (Jotai, persistence, migration safety)
• Architecture patterns for specific systems (IPC, editors, extensions)
• Testing patterns (E2E, unit test guidelines)
• Feature-specific guides (walkthroughs, dialogs, permissions)

Keep in CLAUDE.md

• Critical warnings (database access, security)
• Development setup and commands
• High-level architecture overview
• General development guidelines
• Package structure
• Release process basics

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).