# Modular Large File Refactor > Refactor oversized source files into smaller, coherent modules while reducing complexity and preserving behavior. Use when Claude needs to split a large component, hook, service, command handler, or Rust module; untangle mixed responsibilities; extract helpers or submodules; or reorganize code into a clearer modular design without changing the public contract. - Skill: `fritzprix/modular-large-file-refactor` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add fritzprix/modular-large-file-refactor` - Raw SKILL.md: https://api.skillmd.com/api/skills/fritzprix/modular-large-file-refactor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: fritzprix (https://skillmd.com/u/fritzprix) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fritzprix/modular-large-file-refactor --- # Modular Large File Refactor Refactor one large file into a small set of focused modules without creating a mess of tiny shards. Optimize for lower cognitive load, stable public APIs, and obvious ownership boundaries. ## Workflow 1. Find the real target first. In this repository, start with the bundled `scripts/find_large_files.sh` helper instead of ad-hoc shell pipelines. 2. Inspect the oversized file and list its responsibilities before touching code. 3. Classify each block as one of: public API, orchestration, pure logic, state management, side effects, types, constants, or UI rendering. 4. Choose the smallest useful module split that isolates responsibilities cleanly. 5. Extract in safe order: constants/types first, pure helpers next, stateful logic after that, and orchestration last. 6. Keep the original entrypoint stable unless the current public surface is the problem. 7. Re-run the relevant validation after the split. ## Built-in Large File Finder Use the bundled script first: ```bash bash scripts/find_large_files.sh ``` What it does well: - scans the repo's real source roots - ignores dependency and build directories - highlights severe offenders at `1000+` and `800+` lines - gives a quick ranked list before deeper analysis Use the script output to pick the biggest meaningful source file, then start the modular split. ## Split Decision Rules **Extract a new module when the code has one clear responsibility.** - Pure transforms, parsers, validators, formatters, and mappers belong in their own helpers. - Shared types, schemas, and constants move out early because they reduce noise with low risk. - Repeated UI subsections become components only if they own a meaningful chunk of markup or behavior. - Stateful logic with a clean interface becomes a hook, service, or internal module. **Keep code together when separation would hide the story.** - Do not create `utils.ts` or `helpers.ts` dumping grounds. - Do not split a file just to reduce line count. - Do not move tightly coupled code into distant files if the reader now has to bounce between five places to understand one flow. ## Extraction Order ### 1. Stabilize boundaries - Identify exports that other files already depend on. - Preserve existing names and call shapes unless changing the contract is intentional. - Prefer internal re-exports over churning imports across the repo. ### 2. Remove passive noise - Extract constants, literal maps, small types, and Zod schemas first. - Replace repeated inline conditions or object shapes with named helpers. ### 3. Isolate pure logic - Pull complex branches into named functions with narrow inputs and outputs. - Replace nested conditionals with guard clauses when it improves readability. - Convert anonymous inline callbacks into named functions when they carry real logic. ### 4. Isolate stateful logic - Move reusable or bulky state transitions into hooks, services, or internal modules. - Keep side effects near the orchestration layer; do not bury network or filesystem calls in generic helpers. ### 5. Simplify the entrypoint - Leave the original file as the facade that coordinates extracted parts. - Aim for the top-level file to read like a table of contents for the feature. ## Structural Targets ### React and TypeScript - Put shared UI pieces in sibling component files. - Put non-visual behavior in hooks. - Put backend calls in service modules that match existing project patterns. - Put complex text/data transforms in pure helpers with explicit types. ### Rust - Keep the public module or command handler as the facade. - Move focused logic into sibling modules under the same directory. - Separate parsing, validation, repository access, and response formatting when they are currently interleaved. ### Cross-cutting rule - Prefer a small directory with 3-6 purposeful files over one huge file or fifteen trivial ones. ## Complexity Reduction Moves - Replace long `if/else` ladders with lookup tables only when the behavior is data-driven. - Collapse duplicated setup/teardown into one helper with explicit naming. - Break giant functions by phase: parse -> validate -> execute -> format. - Narrow parameter lists by passing a well-named object only when the fields naturally belong together. - Keep error handling explicit; do not add broad fallback behavior just to make extraction easier. ## Anti-Patterns - Splitting by arbitrary line ranges instead of responsibility - Creating circular imports between extracted modules - Hiding critical behavior in vaguely named helpers - Moving repository or network calls into "pure" utility files - Re-exporting everything from everywhere - Changing filenames, symbols, and call paths more than the refactor requires ## Output Expectation When you finish, describe the refactor in this shape: 1. What responsibilities were identified in the original file 2. Which modules were extracted and why 3. Which public entrypoints stayed stable 4. Which risky areas were checked after the split ## Reference Read `references/splitting-patterns.md` when you need concrete module patterns for React/TypeScript or Rust, or when the right split boundary is not obvious.