Add Deterministic Code Modularization Tool (No LLM Rewriting)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Title:
[FEATURE] Add Deterministic Code Modularization Tool (No LLM Rewriting)

Labels to Add:
enhancement, area:tools

---

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

---

Problem Statement

When refactoring large files into smaller modules, Claude Code currently rewrites the code during the modularization process. This introduces several risks:

• LLM hallucinations can introduce bugs or change behavior
• Loss of exact formatting, comments, and code style
• Slower execution due to token-heavy regeneration
• Unpredictable results across different runs (see #1638)

For production codebases, we need a way to reorganize code structure without any rewriting - essentially a "cut and paste" operation that preserves 100% code fidelity.

---

Proposed Solution

Proposed Solution

Add a deterministic code modularization tool that:

1. Analyzes the file structure to identify logical boundaries
2. Extracts code blocks by moving them (not regenerating)
3. Preserves exact code, formatting, whitespace, and comments
4. Updates imports/exports automatically
5. Validates that the refactored code is functionally identical

This would be similar to IDE refactoring tools (VS Code's "Move to new file") but AI-guided.

---

Example Use Cases

Use Case 1: Split Large Utilities File

Input: utils.js (2000 lines)
Command: "Split this into separate modules by function category, but don't rewrite any code"
Output: 
  - string-utils.js (extracted lines 1-350)
  - date-utils.js (extracted lines 351-580)  
  - validation-utils.js (extracted lines 581-920)
  - [with updated imports in other files]

Use Case 2: Extract Components

Input: Dashboard.jsx (1500 lines with multiple components)
Command: "Extract all sub-components into separate files"
Output:
  - Dashboard.jsx (main component)
  - DashboardHeader.jsx (exact code from lines 45-120)
  - DashboardSidebar.jsx (exact code from lines 121-280)
  - [imports automatically added/updated]

---

Alternative Solutions

Technical Approach

This could work as a new tool/command like /modularize that:

1. Uses AST parsing to identify movable code blocks
2. Performs literal string extraction (not LLM generation)
3. Creates new files with extracted code
4. Updates import statements using AST manipulation
5. Verifies no behavior changes (optional: run tests before/after)

Key difference from current behavior: Zero LLM involvement in the actual code movement - only in identifying what to move and where.

---

Benefits

100% code fidelity - no risk of introduced bugs
Faster execution - no token-heavy regeneration
Deterministic - same input = same output every time
Safe for production - like using IDE refactoring tools
Complements #1638 - addresses the same pain point with a different approach

---

Priority

Medium-High - This would make Claude Code significantly more reliable for production refactoring workflows, which is a core use case for many developers.

---

Alternative Workarounds

Currently, users must:

• Manually verify every line after Claude modularizes code
• Use git diff extensively to catch unintended changes
• Avoid large refactoring tasks due to risk
• Use external tools like sed for deterministic changes (as mentioned in #9868)

---

Related Issues

• #1638 - Claude Code Violates Refactoring Principles
• #9868 - Refactoring large codebase produces inconsistent results
• #6176 - Unintended Code Duplication During Refactoring

---

Additional Context

This feature would position Claude Code as a truly professional-grade refactoring tool, suitable for enterprise codebases where code fidelity is non-negotiable.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Perfect! Here's the content formatted specifically for that GitHub issue template:

---

Title:

[FEATURE] Add Deterministic Code Modularization Tool (No LLM Rewriting)

---

Priority*

High - This feature is critical to my workflow for production refactoring tasks where code fidelity is non-negotiable.

---

Feature Category*

Code Editing & Refactoring

---

Use Case Example

Scenario: Modularizing a Legacy React Component

Current Situation:
I have a Dashboard.jsx file that's grown to 1,800 lines over 2 years. It contains:

• Main Dashboard component (200 lines)
• 5 sub-components inline (1,200 lines total)
• Utility functions (400 lines)
• Everything works perfectly in production

Step-by-Step Workflow:

Step 1: I ask Claude Code to modularize the file

Me: "Split Dashboard.jsx - extract all sub-components into separate files"

Step 2 (Current Behavior - Problem):
Claude Code rewrites the components while moving them:

• Changes variable names for "consistency"
• Reformats code style
• Adds comments it thinks are helpful
• Sometimes changes logic slightly ("improving" it)
• I spend 2 hours doing git diff to verify nothing broke

Step 2 (Desired Behavior - Solution):
Claude Code uses the modularization tool:

• Analyzes AST to identify component boundaries
• Literally cuts and pastes code blocks (lines 45-250, 251-480, etc.)
• Creates new files with exact extracted code
• Updates imports/exports automatically
• Shows me: "Extracted 5 components, 0 lines changed, only imports updated"

Step 3: I run tests - everything passes immediately because the code is identical

Step 4: I commit with confidence, knowing only structure changed, not logic

---

Another Real Example: Splitting utils.js

I have utils.js with 2,500 lines of battle-tested utility functions. I want to split it by category (string utils, date utils, validation, etc.) but:

• Can't use current Claude Code: Risk of bugs in rewritten functions
• Can't do manually: Too time-consuming to track all imports
• Need this tool: Deterministic split + automatic import updates

---

Additional Context

Additional Context

$ claude /modularize Dashboard.jsx --by-components

Analyzing file structure...
Found 5 extractable components:
  ✓ DashboardHeader (lines 45-250)
  ✓ DashboardSidebar (lines 251-480)
  ✓ MetricsPanel (lines 481-720)
  ✓ ActivityFeed (lines 721-1100)
  ✓ QuickActions (lines 1101-1300)

Extracting components (0 lines modified, only moved)...
  ✓ Created DashboardHeader.jsx
  ✓ Created DashboardSidebar.jsx  
  ✓ Created MetricsPanel.jsx
  ✓ Created ActivityFeed.jsx
  ✓ Created QuickActions.jsx

Updating imports...
  ✓ Added 5 imports to Dashboard.jsx
  ✓ Updated 3 imports in other files

✅ Modularization complete
   Files created: 5
   Lines moved: 1,200
   Lines rewritten: 0
   Imports updated: 8

Links to Similar Features in Other Tools

1. VS Code's "Move to new file" refactoring

• Extracts code without rewriting
• Updates imports automatically
• See: https://code.visualstudio.com/docs/editor/refactoring

1. IntelliJ IDEA's "Extract Method/Class"

• Deterministic code extraction
• AST-based, zero rewrites

1. Rope (Python refactoring library)

• Programmatic refactoring without LLM
• https://github.com/python-rope/rope

Technical Considerations

Implementation Approach:

1. Use AST parsers (Babel for JS/TS, Python AST for Python, etc.)
2. Identify extraction boundaries via LLM analysis
3. Perform extraction via string slicing (not LLM generation)
4. Update imports via AST manipulation tools (e.g., jscodeshift)
5. Optional: Run tests to verify behavior unchanged

Key Technical Constraint:

• Must support multiple languages (JS/TS, Python, Java, etc.)
• Consider using language-specific AST libraries
• Fall back to regex/string manipulation if AST unavailable

Why LLM-free extraction is critical:

• No hallucination risk
• Deterministic results
• Much faster (no token generation)
• Can be verified with simple diff

Related Issues & Context

• #1638 - Claude Code Violates Refactoring Principles (this addresses the root cause)
• #9868 - Refactoring produces inconsistent results (determinism solves this)
• #6176 - Unintended code duplication (extraction would prevent this)

Security Considerations

This feature enhances security by:

• Reducing risk of introduced bugs during refactoring
• Maintaining exact code behavior (no logic changes)
• Making code reviews faster (only structural changes to review)

---