2167. Identidad de la lección
Esta lección trata la refactorización como un cambio estructural controlado. La implementación puede reorganizarse, renombrarse o dividirse, pero el comportamiento de juego acordado debe seguir siendo observable y comprobable.
2168. Objetivo de aprendizaje
Al finalizar esta lección, podrás definir una línea base de comportamiento, ejecutar una refactorización por etapas y comparar la evidencia anterior y posterior para determinar si el contrato conservado sigue cumpliéndose.
2169. Por qué es importante
Una refactorización puede mejorar la estructura y cambiar silenciosamente los tiempos, costes, transiciones de estado o resultados visibles para el jugador. El riesgo aumenta cuando una herramienta de IA modifica varios archivos relacionados en una sola respuesta. Un contrato de comportamiento establece un límite estable para decidir si el cambio es estructural o si realmente modifica el juego. También te permite revisar evidencia en lugar de confiar en que el proyecto compile o en una inspección rápida del diff.
2170. Conocimientos previos
Debes haber completado 5.6 L2 — Plan a staged multi-system change. Debes poder identificar dependencias, dividir un cambio entre varios sistemas en etapas revisables y definir la evidencia necesaria para continuar. También debes saber ejecutar las comprobaciones relevantes del proyecto e inspeccionar un diff de Git.
2171. Core concept
Una refactorización cambia la forma en que se implementa un comportamiento sin cambiar intencionadamente el comportamiento prometido por el contrato.
El contrato debe expresarse en términos observables. Puede incluir:
- entradas aceptadas y precondiciones necesarias;
- cambios de estado y su orden;
- costes, recompensas y otros valores visibles para el jugador;
- eventos emitidos o llamadas necesarias para los sistemas conectados;
- expectativas de persistencia;
- comportamiento ante errores y respuesta mostrada al jugador.
El contrato no es la distribución actual de clases, el nombre de una función, la ubicación de un archivo ni la estructura interna de datos. Son detalles de implementación, salvo que otro sistema o herramienta externa dependa de ellos.
La distinción útil es esta:
| Pregunta | Refactorización estructural | Cambio de comportamiento de juego |
|---|---|---|
| ¿Qué cambia? | Organización, límites, nombres, duplicación o dependencias | Reglas, valores, tiempos, estados o resultados visibles |
| ¿Qué debe permanecer estable? | El contrato de comportamiento | Nada se da por estable sin una decisión de diseño nueva |
| ¿Qué evidencia hace falta? | Observaciones equivalentes antes y después | Criterios de aceptación y evidencia o pruebas actualizadas |
2172. Mental model
Usa el modelo Línea base → Punto de separación → Un movimiento → Comparación:
- Línea base: registra el comportamiento que debe permanecer estable antes de editar.
- Punto de separación: elige el límite más pequeño donde pueda cambiar la estructura sin redefinir el contrato.
- Un movimiento: realiza un cambio estructural coherente, detente e inspecciónalo.
- Comparación: repite las mismas comprobaciones observables y compara los resultados con la línea base.
Antes de pedir una edición a la IA, expresa el contrato en una tabla:
| Escenario | Precondiciones | Acción | Estado o resultado esperado | Evidencia |
|---|---|---|---|---|
| Ruta normal | Qué debe ser cierto | Qué hace el jugador o sistema | Qué permanece cierto después | Repetición, prueba, registro o captura |
| Ruta rechazada | Qué invalida la acción | Acción inválida | El estado y la respuesta siguen siendo correctos | Prueba o salida capturada |
| Ruta límite | Límite o transición relevante | Acción en el límite | El comportamiento del límite permanece correcto | Prueba, registro o repetición |
Una compilación correcta es solo una señal. Demuestra que el proyecto compila o carga; no demuestra que el contrato haya sobrevivido.
2173. Concrete example
Supón que el cálculo de una recompensa está mezclado actualmente con un controlador. La refactorización prevista consiste en trasladar el cálculo a un servicio dedicado y dejar que el controlador se encargue de la coordinación.
Antes del cambio, define observaciones como estas:
- una finalización válida concede la misma cantidad de recompensa;
- una finalización inválida no concede recompensa;
- el estado de progresión relevante cambia una sola vez, no dos;
- la confirmación visible para el jugador sigue apareciendo bajo la misma condición;
- una entrada repetida o situada en el límite no genera una recompensa adicional.
Extraer el servicio es un cambio estructural si esas observaciones siguen siendo ciertas. Cambiar la cantidad de recompensa, el momento en que avanza la progresión o el mensaje de rechazo no es solo estructura. Son decisiones de juego y deben tratarse como un cambio separado, con criterios de aceptación nuevos.
2174. AI-native workflow
Usa la IA como asistente de implementación, no como autoridad sobre la conservación del contrato.
- Proporciona al agente el contrato, la evidencia de referencia, el punto de separación previsto y los objetivos no incluidos.
- Pídele que proponga el conjunto mínimo de archivos y símbolos para el primer movimiento estructural. Exige que identifique los comportamientos que podrían verse afectados.
- Revisa la propuesta. Rechaza cualquier paso que cambie reglas, valores, tiempos o comportamiento visible sin una decisión deliberada.
- Pide una edición acotada, no una limpieza general. Indica que debe conservar las interfaces públicas o crear una capa de compatibilidad explícita si fuese necesaria.
- Inspecciona el diff antes de ejecutar las comprobaciones. Busca cambios accidentales en el orden de condiciones, valores predeterminados, emisión de eventos, gestión de errores y propiedad del estado.
- Ejecuta las mismas comprobaciones usadas para la línea base. Puedes pedir a la IA que compare las observaciones, pero la decisión final te corresponde.
Una solicitud útil sería:
Refactoriza únicamente la estructura descrita a continuación. Conserva cada contrato y objetivo no incluido. Primero propone la edición escalonada más pequeña. No cambies valores de juego, orden de transiciones de estado, tiempos, comportamiento ante errores ni texto visible para el jugador. Después de editar, enumera cada contrato y la evidencia que debe verificarlo.
No aceptes una afirmación como «el comportamiento debería ser igual» como evidencia. Exige una observación comprobable.
2175. Git workflow
Crea un punto de revisión antes del cambio estructural, siguiendo el flujo del repositorio establecido para el proyecto. Conserva la evidencia de referencia junto al registro del cambio o en la ubicación de verificación que ya use el proyecto. Después:
- inspecciona el estado de trabajo antes de editar;
- mantén la primera etapa de la refactorización suficientemente acotada para revisarla;
- inspecciona el diff después de cada movimiento limitado;
- evita mezclar cambios de formato, limpieza no relacionada y cambios de juego en el mismo cambio;
- registra qué comprobaciones ejecutaste y si coinciden con la línea base;
- conserva la posibilidad de revertir el movimiento estructural sin perder trabajo ajeno.
Un commit o punto de control equivalente no demuestra que el resultado sea correcto. Es un límite de recuperación y revisión.
2176. Common mistake
El error habitual es considerar que una compilación correcta, una captura sin cambios o un diff pequeño demuestran que el contrato se conservó. Una refactorización puede compilar y aun así modificar un valor predeterminado, emitir dos veces un evento, avanzar el estado antes de tiempo o alterar la ruta de acción inválida. Compara los mismos escenarios y observaciones antes y después de editar.
Otro error es permitir que la IA combine la refactorización con una «limpieza» de reglas de juego. Si el agente cambia nombres, arquitectura, valores de balance y reglas de casos límite en una sola pasada, ya no podrás saber qué cambio provocó una diferencia de comportamiento. Separa el trabajo estructural de los cambios de comportamiento.
2177. Guided practice
Realiza una refactorización controlada en una parte pequeña y aislada del proyecto o en un área de práctica existente.
Paso 1 — Elige el límite
Selecciona un fragmento de código con una responsabilidad clara y al menos un llamador. No elijas una limpieza amplia. Escribe una frase que describa el cambio estructural, por ejemplo: «trasladar la responsabilidad X detrás del límite Y».
Paso 2 — Define la línea base
Completa una tabla de contrato con al menos tres escenarios:
- una ruta normal;
- una ruta rechazada o de error;
- una ruta límite, una entrada repetida o una transición de estado.
Para cada escenario, captura evidencia observable. Usa las pruebas, registros, pasos de repetición, capturas o valores de estado disponibles en el proyecto. Registra los valores exactos cuando sean importantes.
Paso 3 — Solicita una propuesta escalonada
Entrega a la IA el contrato y los objetivos no incluidos. Pide una propuesta que contenga:
- la primera edición más pequeña;
- los archivos y símbolos afectados;
- las dependencias que deben seguir siendo compatibles;
- los riesgos para el contrato;
- la comprobación que debe ejecutarse inmediatamente después.
Decide si aceptas, acotas o rechazas la propuesta. Tu decisión forma parte del ejercicio.
Paso 4 — Ejecuta un movimiento estructural
Aplica solamente el movimiento aceptado. Conserva los valores y condiciones relacionados con el comportamiento, salvo que el movimiento no pueda completarse sin modificarlos. Si aparece un cambio de comportamiento necesario, detente y clasifícalo como una decisión de diseño separada en lugar de incluirlo silenciosamente.
Paso 5 — Compara la evidencia
Ejecuta los mismos escenarios de la línea base. Compara estado, valores, cantidad de eventos, observaciones sensibles al tiempo cuando corresponda y respuesta visible para el jugador. Inspecciona el diff y anota cualquier discrepancia, aunque parezca beneficiosa.
Paso 6 — Decide el resultado
Clasifica el resultado como una de estas opciones:
- Conservado: todas las observaciones requeridas coinciden y el diff está dentro del límite estructural declarado;
- Necesita corrección: una observación del contrato difiere o el diff contiene un cambio de comportamiento no previsto;
- No es una refactorización: el cambio solicitado requiere un contrato de juego nuevo y debe replantearse como trabajo de comportamiento.
Si el resultado no se conserva, revierte o corrige el movimiento acotado antes de intentar otro cambio estructural.
2178. Validation / evidence
Tu trabajo está completo cuando puedes señalar todo lo siguiente:
- un contrato escrito con al menos tres escenarios observables;
- un estado anterior o línea base registrada para cada escenario;
- una propuesta de IA que identifica alcance, riesgos y objetivos no incluidos;
- un diff pequeño que muestra el movimiento estructural;
- evidencia posterior de los mismos escenarios;
- una comparación que indique si se conservó cada elemento del contrato;
- una decisión que explique por qué el resultado es una refactorización conservada, una corrección o un cambio de comportamiento que requiere planificación separada.
Rúbrica práctica de evaluación
Puntúa cada criterio de 0 a 2: 0 = ausente, 1 = incompleto o con respaldo insuficiente, 2 = completo y respaldado por evidencia observable.
- Línea base completa: incluye una ruta normal, una ruta rechazada o de error y una ruta límite o de entrada repetida.
- Control del alcance: declara el límite estructural y los aspectos fuera del alcance, sin mezclar limpieza no relacionada ni cambios de comportamiento.
- Ejecución de un solo movimiento: aplica un cambio estructural coherente y se detiene para revisarlo.
- Equivalencia antes y después: repite las mismas comprobaciones y demuestra si coincide cada observación del contrato.
- Revisión del diff: comprueba valores, condiciones, eventos, transiciones de estado y efectos visibles para el jugador.
- Capacidad de reversión: conserva un punto de recuperación claro que permite revertir el cambio sin perder trabajo no relacionado.
- Decisión final: clasifica el resultado como conservado, pendiente de corrección o sujeto a replanteamiento, y justifica la decisión con evidencia.
Una entrega satisfactoria obtiene al menos 12 de 14 puntos y recibe 2 puntos en equivalencia antes y después. Si no se demuestra esa equivalencia, la refactorización todavía no está validada, independientemente de la puntuación total.
La evidencia más sólida combina comprobaciones automatizadas con al menos una observación del comportamiento en ejecución cuando la refactorización afecta una ruta de ejecución. Una compilación limpia, por sí sola, no es suficiente.
2179. Key takeaways
- Una refactorización es estructural solo cuando su contrato de comportamiento permanece estable.
- Define evidencia observable de referencia antes de cambiar la estructura.
- Haz un movimiento acotado cada vez e inspecciona el diff antes de continuar.
- La IA puede proponer y ejecutar el movimiento; el desarrollador debe definir el contrato y juzgar la evidencia.
- Los cambios de juego descubiertos durante la refactorización deben separarse y replantearse, no ocultarse dentro de la limpieza.
2180. Siguiente lección
Continúa con 5.7 L2 — Rechazar una abstracción atractiva pero insegura.
2181. Comprobación
Responde estas preguntas por tu cuenta antes de leer las respuestas.
¿Qué elemento pertenece a una línea base de comportamiento para una refactorización?
Mostrar respuesta y explicación
Respuesta: Un resultado observable para un escenario definido, como un cambio de estado o una recompensa.
Por qué: Una línea base de comportamiento registra lo que puede observarse y compararse antes y después del cambio. La estructura de archivos y la preferencia del agente son detalles de implementación, no pruebas de comportamiento conservado.
¿Cuál es la solicitud inicial más segura para hacerle a un agente de IA durante esta refactorización?
Mostrar respuesta y explicación
Respuesta: Pedirle que proponga la edición más pequeña, sus riesgos y la comprobación posterior.
Por qué: Una propuesta pequeña con riesgos explícitos y evidencia posterior mantiene el cambio revisable y evita incluir cambios de comportamiento no relacionados.
La refactorización compila, pero una entrada repetida ahora concede la recompensa dos veces. ¿Cómo debe clasificarse este resultado?
Mostrar respuesta y explicación
Respuesta: Necesita corrección, porque cambió un elemento observable del contrato.
Por qué: El escenario de entrada repetida forma parte de la línea base observable. Conceder la recompensa dos veces cambia el comportamiento, por lo que el movimiento acotado necesita corrección antes de continuar.
¿Qué cambio debe separarse de una refactorización que conserva el comportamiento?
Mostrar respuesta y explicación
Respuesta: Cambiar la cantidad de recompensa y la condición que hace avanzar la progresión.
Por qué: Cambiar los valores de recompensa o las condiciones de progresión modifica las reglas del juego. Requiere una decisión de comportamiento separada y criterios de aceptación actualizados, en lugar de ocultarse dentro de una refactorización estructural.