/refactor

Intelligently restructures code while maintaining functionality and automatically updating all dependencies.

This command is designed for safely executing complex refactoring tasks, such as breaking up large files, extracting reusable components, or improving code organization.

Auto-Loaded Project Context:

@/CLAUDE.md
@/docs/ai-context/project-structure.md
@/docs/ai-context/docs-overview.md

Command Execution

The /refactor command follows a careful, analysis-driven process to ensure changes are safe and effective.

Step 1-2: Parse and Validate Files

The AI first parses your arguments to identify all files tagged with @ for refactoring. It verifies that each file exists before proceeding.

Step 3: Intelligent Analysis Strategy Decision

For each file, the AI assesses its complexity and decides on an analysis strategy:

  • Direct Refactoring: For simple files with clear split points and minimal dependencies.
  • Focused/Comprehensive Analysis: For complex files, it designs and launches a team of specialized sub-agents to analyze the code from multiple angles (file structure, dependency network, project patterns, impact assessment).

Step 4: Execute Chosen Strategy

If sub-agents are used, they are launched in parallel to gather all necessary information for a safe refactoring.

Step 5: Synthesize Analysis and Plan Refactoring

The AI combines the findings from its analysis to create an optimal refactoring plan. This plan includes:

  • How many new files to create.
  • Where to place them in the directory structure.
  • A strategy for updating all import/export statements across the entire codebase that are affected by the change.

Step 6: Refactoring Value Assessment

This is a critical step. Before executing the plan, the AI critically evaluates whether the proposed refactoring will actually improve the codebase. It weighs positive indicators (e.g., reduces complexity, improves testability) against negative ones (e.g., creates artificial boundaries, introduces unnecessary complexity).

  • If the refactoring is worthwhile, it prints a summary of the benefits and proceeds automatically.
  • If the refactoring is not recommended, it will be brutally honest, explain why, and ask for your explicit confirmation before proceeding.

❌ Example Message: "This refactoring is not recommended because the file, while large, serves a single, cohesive purpose. Splitting it would make the logic harder to follow. Do you still want to proceed? (yes/no)"

Step 7: Execute Refactoring

If the refactoring is approved (either automatically or by you), the AI executes the plan. It carefully creates new directories and files, moves the code, and then meticulously updates all import/export statements throughout the project to point to the new locations.

Step 8: Quality Verification

After the refactoring is complete, the AI runs checks to verify that all imports resolve correctly and that the new structure follows project patterns.

Finally, it provides a comprehensive summary of the entire operation.