Refactorización con Codex: plan, objetivo y una revisión en cada paso

Qué hace Codex 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 Codex para refactorización

Cómo configurar Codex 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 Codex pueda ejecutar y un límite al tamaño de cada paso, así que pon las dos cosas en AGENTS.md.

   # En la CLI: acuerda el plan y luego fija la meta
   /plan Propose a migration plan for the billing module
   /goal Finish the migration and keep tests green

2. Escribe las reglas en AGENTS.md

   Codex lee AGENTS.md antes de empezar a trabajar: ~/.codex/AGENTS.md y después los archivos desde la raíz del repositorio hasta la carpeta en la que trabaja. Pon ahí las reglas del trabajo, o en una skill dentro de .agents/skills/ si son largas. Consulta la guía de AGENTS.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

   codex exec ejecuta una tarea y termina. El progreso va a stderr y el mensaje final a stdout; -o también lo escribe en un archivo y --json emite los eventos en streaming. El sandbox es de solo lectura salvo que pases --sandbox workspace-write.

   # El primer día, y luego la misma sesión al día siguiente
   codex exec --sandbox workspace-write "Haz el primer paso de REFACTOR.md"
   codex exec resume --last "Continúa con el siguiente paso sin marcar de REFACTOR.md"

4. Ponlo en un horario

   Crea una tarea programada en la app de escritorio de ChatGPT o en la web (la CLI no las gestiona), o ejecuta codex exec desde cron. Consulta cómo hacer que Codex sea proactivo.

Fuente: documentación de Codex

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.
• Codex ejecuta los comandos en un sandbox por defecto: las escrituras se quedan en el workspace y la red está desactivada. Reserva danger-full-access para un runner o un contenedor aislado.

¿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 Claude Code.

Dale a alguien el trabajo de refactorización

Los comandos se ejecutan cuando alguien se acuerda de ejecutarlos. Crewmark convierte tu propio Codex 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