| name | file-refactor |
| description | Keep source files under 500 lines. Split files that mix concerns — types, utils, hooks, sub-components, constants. Use when a file approaches the limit or when the user says refactor file, split file, too long, or file too big.
|
File Refactor
Keep every source file under 500 lines. Split before it crosses the limit.
When to trigger
- A file exceeds 500 lines
- A module mixes types, utils, handlers, rendering, and constants
- A screen component contains inline sub-components that are extractable
- A service combines pure helpers, dataclasses, and orchestration in one file
TypeScript / React splitting order
- Types — interfaces, type aliases, enums →
types.ts
- Pure utilities — formatting, grouping, transforms →
utils.ts
- Complex state logic →
hooks/useXxx.ts
- Sub-components — UI pieces →
components/XxxYyy.tsx
- Constants / config — hardcoded arrays, config objects →
constants.ts
Python splitting order
- Data models —
@dataclass, TypedDict, Protocol → models.py
- Pure helpers — side-effect-free formatting/parsing →
utils.py or *_format.py
- Orchestration — original file stays as coordinator (CLI entry, service facade)
- CLI groups — subcommand handlers → dedicated modules
- Constants — templates, frozensets →
constants.py
Rules
- Single responsibility — each file does one thing
- Cohesion — related code stays together
- Preserve exports — never break existing imports; re-export from original file if needed
- Mirror neighbors — follow existing package layout; don't invent new patterns
- After splitting: typecheck + lint must pass
