large-file-refactor

Large File Refactoring

Guide for analyzing and breaking apart files that exceed Claude Code's read limits.

When This Applies

• Token limit error: "File content (X tokens) exceeds maximum allowed tokens (25000)"
• Files > 2000 lines: Likely to cause issues or be hard to maintain
• User request: "break apart", "split", "refactor large file"

Quick Start Algorithm

1. Assess the File

# Get line count
wc -l <file>

# Get structure overview (Rust example)
grep -n "^pub fn\|^fn\|^impl\|^struct\|^enum\|^mod" <file>

Use LSP documentSymbol for accurate symbol outline.

2. Identify Natural Breakpoints

Look for cohesive groups:

• Related functions (CRUD operations, handlers, validators)
• Type + its impl blocks
• Feature-specific code
• Test modules

3. Plan the Breakout

Target: Each new file should be 200-500 lines (readable in one read).

4. Execute Refactor

1. Create new file(s)
2. Move code with Read (offset/limit) + Write
3. Update imports/exports
4. Update the original file's module declarations

5. Validate

• All imports resolve (LSP hover, no red squiggles)
• Tests pass
• No circular dependencies
• Original functionality preserved

Analysis Without Full Read

When you can't read the whole file:

Example workflow:

1. wc -l file.rs                    # 3500 lines
2. grep -n "^impl" file.rs          # Find impl blocks at lines 100, 800, 2000
3. LSP documentSymbol file.rs       # Get full structure
4. Read file.rs offset=100 limit=200  # Read first impl block

Breakout Decision Matrix

Language-Specific Patterns

See @large-file-refactor/references/breakout-patterns.md for detailed examples.

Common Pitfalls

1. Breaking public API: Ensure exports remain accessible
2. Circular imports: Plan dependency direction before splitting
3. Lost context: Keep related code together (don't over-split)
4. Forgetting tests: Move/update test imports too

References

• @large-file-refactor/references/analysis-strategies.md - Detailed analysis techniques
• @large-file-refactor/references/breakout-patterns.md - Language-specific examples
• @large-file-refactor/references/validation-checklist.md - Pre/post refactor checks