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

bash

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

Pattern	When to Use
Extract to submodule	Related impl blocks, feature code
Extract to sibling file	Independent utilities, types
Create package/directory	Multiple related modules

4. Execute Refactor

Create new file(s)
Move code with Read (offset/limit) + Write
Update imports/exports
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:

Tool	Use For
`Grep`	Find definitions: `^fn`, `^class`, `^def`, `impl`
`LSP documentSymbol`	Get complete symbol outline
`Read` with offset/limit	Read specific sections
`wc -l`	Total line count

Example workflow:

text

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

File Size	Recommendation
< 500 lines	Usually fine as-is
500-1000 lines	Consider splitting if multiple concerns
1000-2000 lines	Should split unless highly cohesive
> 2000 lines	Must split for maintainability

Language-Specific Patterns

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

Language	Primary Pattern
Rust	Submodules in directory, re-export from mod.rs
TypeScript	Separate files, barrel export from index.ts
Python	Package with init.py
Go	Multiple files in same package

Common Pitfalls

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

References

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

Search AI Tools

large-file-refactor

Install this agent skill to your Project

SKILL.md