Refactorización con Claude Code: plan, pasos pequeños y tests en verde

Qué hace Claude Code para refactorización

• Avanza por un backlog de refactorización en pasos pequeños, cada uno en su propia pull request.
• Ejecuta los tests antes y después de cada paso, y se detiene cuando fallan.
• Hace la parte mecánica de las migraciones: renombrados en todo el código, actualizaciones de APIs, el paso a una librería nueva.
• Elimina código muerto y lógica duplicada, y explica cada eliminación.

Funciones de Claude Code para refactorización

Cómo configurar Claude Code para refactorización

1. Conecta las herramientas

   No hay nada que conectar. Lo que hace segura una refactorización es un comando de tests que Claude pueda ejecutar y un límite al tamaño de cada paso, así que pon las dos cosas en CLAUDE.md y empieza en un worktree.

   # Empieza la refactorización en su propio worktree
   claude --worktree billing-async
   
   # Acuerda el plan antes de editar nada
   /plan Move the billing module from callbacks to async/await

2. Escribe las reglas en CLAUDE.md

   Claude Code lee CLAUDE.md al empezar cada sesión, también en las ejecuciones con claude -p. Pon ahí las reglas del trabajo, o en una skill dentro de .claude/skills/ si son largas. Consulta la guía de CLAUDE.md.

   ## Reglas de refactorización
   - Ningún cambio de comportamiento. Si un test tiene que cambiar, para
     y pregunta.
   - Ejecuta `npm test` antes de empezar y después de cada paso.
   - Un paso por pull request, de menos de 400 líneas cambiadas.
   - Mantén REFACTOR.md al día: marca lo que está hecho y añade lo
     que encuentres.
   - No toques migrations/, los archivos generados ni las APIs públicas
     sin preguntar.

3. Ejecútalo sin la interfaz interactiva

   claude -p ejecuta una tarea y termina, así que puede lanzarlo cron, la CI u otra herramienta. Decide qué puede hacer sin preguntar con --allowedTools o --permission-mode; --output-format json devuelve el resultado junto con su coste.

   # Un paso al día del backlog de REFACTOR.md
   claude -p "Haz el siguiente punto sin marcar de REFACTOR.md y mantén los tests en verde" \
     --allowedTools "Bash(npm test),Read,Edit"

4. Ponlo en un horario

   Conviértelo en una tarea programada en la nube con /schedule (Pro, Max, Ultra, Team y Enterprise) o en una tarea programada de escritorio, o usa /loop mientras la sesión siga abierta. Consulta cómo hacer que Claude Code sea proactivo.

Fuente: documentación de Claude Code

Límites y seguridad

• Sin tests no puede distinguir una refactorización de un cambio de comportamiento. Añade primero tests para esa parte del código.
• Una gran reescritura de una sola vez es difícil de revisar. Los pasos pequeños que se van integrando son más seguros y, al final, más rápidos.
• No sabe qué código raro es intencionado. Marca esos sitios con un comentario o en las reglas.
• Desde Claude Code v2.1.302, claude -p arranca en modo Manual: se deniega cualquier acción que necesite aprobación salvo que una regla la permita. Permite solo las herramientas que el trabajo necesita.

¿Claude Code o Codex para refactorización?

Las reglas sirven para los dos. Escríbelas una vez en AGENTS.md y pon @AGENTS.md en CLAUDE.md, y los dos agentes leerán el mismo archivo.

Paso a paso con el otro agente: refactorización con Codex.

Dale a alguien el trabajo de refactorización

Los comandos se ejecutan cuando alguien se acuerda de ejecutarlos. Crewmark convierte tu propio Claude Code en un empleado de IA con un rol, un objetivo en cifras, horario laboral y un heartbeat, para que el trabajo se haga según un horario y aparezca en un tablero.

1. Empieza por el rol

   El ingeniero de software de IA, con estas reglas en su brief.

2. Lleva el trabajo a su tablero

   Añade el trabajo como issue recurrente. El empleado se despierta con su heartbeat, lo hace e informa en un comentario.

3. Relacionado

   Revisión de código comprueba cada paso antes del merge.

Preguntas frecuentes