# Split Large Source File

Refactors a source file over 1200 lines into cohesive modules without changing behavior.

- Repository: https://github.com/lobehub/lobehub (83676 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add lobehub/lobehub --skill split-large-file -g -a claude-code -y`
Codex: `npx skills add lobehub/lobehub --skill split-large-file -g -a codex -y`
Cursor: `npx skills add lobehub/lobehub --skill split-large-file -g -a cursor -y`
Gemini CLI: `npx skills add lobehub/lobehub --skill split-large-file -g -a gemini-cli -y`

## Description

Refactor a source file over 1200 lines into a directory of cohesive modules without changing behavior, test-first. Use when asked to split, decompose, or shrink a large file (拆分大文件, 拆文件, 重构大文件); with no file given, pick one.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Split a Large File

Split one file into a directory of modules without changing behavior. Where the pieces go, what they are named, and where tests live are owned by `source-layout`; read it first. This skill owns the procedure: lock behavior with tests, move, extract, then split the tests.

The split changes no behavior. If you find a bug on the way, note it and fix it in a separate commit or PR after the split.

## 1. Pick the file

Given a file, use it. Otherwise build a shortlist:

```bash
git ls-files -z -- 'src/*.ts' 'src/*.tsx' 'apps/*.ts' 'apps/*.tsx' 'packages/*.ts' 'packages/*.tsx' \
  | rg --null-data -v '(^|/)(__tests__|__mocks__|fixtures|locales)/|\.(test|spec)\.|\.d\.ts$' \
  | xargs -0 wc -l | awk '$1 > 1200 && $NF != "total"' | sort -rn | head -30
```

The shortlist still contains data tables and generated code; filter it by reading. Prefer a file with:

- **A real extraction boundary**: hand-written logic with separable state, sub-domains, or stages, not a lookup table.
- **A repeatable verification surface**: behavior that unit or integration tests can observe (including the real-database tests `testing` requires for models), not one that needs a browser session or live third-party calls.
- **A reviewable scope**: one PR can hold the split. When this repository is mounted as a submodule, split a file of the submodule only through a PR to the submodule.

Use recent churn (`git log --since=3.months --oneline -- <file> | wc -l`) only to break ties. State the choice and the reason before starting.

## 2. Read and plan

Read the whole file and its tests. Find every reference with `rg` on the module path and basename across source roots: imports, re-exports, dynamic `import()`, `vi.mock('…/Foo')`, explicit extensions, and package entry mappings.

Write a short plan before editing:

The rest: https://github.com/lobehub/lobehub/blob/HEAD/.agents/skills/split-large-file/SKILL.md