Workflow Refactoring

Extract a Module

Workflow for splitting a large file into focused modules

refactoringmodulesorganization
CLAUDE.md

When splitting a large file into modules:

  1. Identify groups of related functions, types, and constants that serve a single purpose.
  2. Verify the existing code has tests. If not, add characterization tests before refactoring.
  3. Create a new file for each logical group. Name it after its responsibility.
  4. Move the related code to the new file. Update imports in the original file to reference the new module.
  5. Update all other files that imported the moved code to use the new paths.
  6. Run the tests after each move to catch broken imports immediately.
  7. Verify the original file is smaller and more focused. Each file should have a clear, single responsibility.

Copy this workflow into your CLAUDE.md or agent config file so your agent follows this process automatically.

get crystl