Notas prácticas: refactorización agéntica, o cómo usar agentes para revelar la escultura
Recorrido práctico sobre la refactorización agéntica: contratos, comprobaciones y huecos para código listo para usar, para equipos que despliegan este patrón.
Estas notas reconstruyen un camino práctico en torno a «Agentic Refactoring — Using Agents to Reveal the Sculpture from Vibe-Coded Rock». El foco está en contratos, comprobaciones y huecos para código listo para usar, no en discursos motivacionales. En la etapa «Visión general», anota primero el contrato: entradas necesarias, señal de éxito y qué ocurre ante un fallo parcial. Esa lista mantiene honestos los cambios de código posteriores. Mejor unidades pequeñas y comprobables que scripts kilométricos. Cuando un paso falla, el fallo debería señalar una única responsabilidad y no un pipeline enredado.
El punto de partida
La etapa «Punto de partida» funciona mejor si se trata como una superficie medible. Guarda una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trata esta etapa como un contrato entre entradas y salidas validadas. Nombra los artefactos, define comprobaciones de éxito y no aceptes finalizaciones parciales silenciosas. Mantén el estado del grafo plano y tipado. Los blobs anidados ocultan qué nodo escribió cada campo y rompen la reanudación tras una interrupción.
Primer corte: abstracciones y contratos
La etapa «Primer corte: abstracciones y contratos» funciona mejor si se trata como una superficie medible. Guarda una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registra tiempos y coste en tokens o consultas junto a los resultados funcionales. Ver el coste desde el principio evita facturas inesperadas cuando el flujo pasa de la demo a entornos compartidos. Mantén el estado del grafo plano y tipado. Los blobs anidados ocultan qué nodo escribió cada campo y rompen la reanudación tras una interrupción.
Crear una abstracción de la arquitectura
La etapa «Abstracción de la arquitectura» funciona mejor si se trata como una superficie medible. Guarda una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantén la configuración fuera del código de la aplicación. Archivos de entorno, almacenes de secretos y feature flags deben estar en un único lugar que los operadores puedan auditar sin leer todo el grafo. Mantén el estado del grafo plano y tipado. Los blobs anidados ocultan qué nodo escribió cada campo y rompen la reanudación tras una interrupción. La etapa «Abstracción de la arquitectura» funciona mejor si se trata como una superficie medible. Guarda una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mejor unidades pequeñas y comprobables que scripts kilométricos. Cuando un paso falla, el fallo debería señalar una única responsabilidad y no un pipeline enredado.
Eliminar la complejidad evidente
Para la etapa «Eliminar la complejidad evidente», define las entradas, el responsable del paso y los criterios de salida antes de tocar el código. Los operadores deberían poder relanzar el paso desde un punto de control conocido sin adivinar estado oculto. Trata esta etapa como un contrato entre entradas y salidas validadas. Nombra los artefactos, define comprobaciones de éxito y no aceptes finalizaciones parciales silenciosas. Pon aprobación humana en las transiciones que gastan dinero o cambian datos de producción. Que todo esté conectado en tiempo de compilación no significa que el negocio esté completo.
Los tests estorbaban
Para la etapa «Los tests estorbaban», define las entradas, el responsable del paso y los criterios de salida antes de tocar el código. Los operadores deberían poder relanzar el paso desde un punto de control conocido sin adivinar estado oculto. Registra tiempos y coste en tokens o consultas junto a los resultados funcionales. Ver el coste desde el principio evita facturas inesperadas cuando el flujo pasa de la demo a entornos compartidos. Pon aprobación humana en las transiciones que gastan dinero o cambian datos de producción. Que todo esté conectado en tiempo de compilación no significa que el negocio esté completo.
Inversión de dependencias: dónde ayudó
Para la etapa «Inversión de dependencias: dónde ayudó», define las entradas, el responsable del paso y los criterios de salida antes de tocar el código. Los operadores deberían poder relanzar el paso desde un punto de control conocido sin adivinar estado oculto. Mantén la configuración fuera del código de la aplicación. Archivos de entorno, almacenes de secretos y feature flags deben estar en un único lugar que los operadores puedan auditar sin leer todo el grafo. Pon aprobación humana en las transiciones que gastan dinero o cambian datos de producción. Que todo esté conectado en tiempo de compilación no significa que el negocio esté completo. Para la etapa «Inversión de dependencias: dónde ayudó», define las entradas, el responsable del paso y los criterios de salida antes de tocar el código. Los operadores deberían poder relanzar el paso desde un punto de control conocido sin adivinar estado oculto. Mejor unidades pequeñas y comprobables que scripts kilométricos. Cuando un paso falla, el fallo debería señalar una única responsabilidad y no un pipeline enredado.
Revelar el modelo de dominio
En la etapa «Revelar el modelo de dominio», anota primero el contrato: entradas necesarias, señal de éxito y qué ocurre ante un fallo parcial. Esa lista mantiene honestos los cambios de código posteriores. Trata esta etapa como un contrato entre entradas y salidas validadas. Nombra los artefactos, define comprobaciones de éxito y no aceptes finalizaciones parciales silenciosas. Cachea las instrucciones de sistema y los esquemas de herramientas que no cambian. Reenviar el mismo preámbulo una y otra vez es una fuente habitual de gasto.
Cómo trabajar con el equipo de agentes
En la etapa «Trabajar con el equipo de agentes», anota primero el contrato: entradas necesarias, señal de éxito y qué ocurre ante un fallo parcial. Esa lista mantiene honestos los cambios de código posteriores. Registra tiempos y coste en tokens o consultas junto a los resultados funcionales. Ver el coste desde el principio evita facturas inesperadas cuando el flujo pasa de la demo a entornos compartidos. Pon un punto de control tras los pasos caros. Reanudar no debería volver a cobrar la misma llamada al LLM cuando un operador reintenta un nodo posterior.
La arquitectura por fin se hizo visible
En la etapa «La arquitectura por fin se hizo visible», anota primero el contrato: entradas necesarias, señal de éxito y qué ocurre ante un fallo parcial. Esa lista mantiene honestos los cambios de código posteriores. Mantén la configuración fuera del código de la aplicación. Archivos de entorno, almacenes de secretos y feature flags deben estar en un único lugar que los operadores puedan auditar sin leer todo el grafo. Pon un punto de control tras los pasos caros. Reanudar no debería volver a cobrar la misma llamada al LLM cuando un operador reintenta un nodo posterior. En la etapa «La arquitectura por fin se hizo visible», anota primero el contrato: entradas necesarias, señal de éxito y qué ocurre ante un fallo parcial. Esa lista mantiene honestos los cambios de código posteriores. Mejor unidades pequeñas y comprobables que scripts kilométricos. Cuando un paso falla, el fallo debería señalar una única responsabilidad y no un pipeline enredado.
Cómo se creó este artículo
La etapa «Cómo se creó este artículo» funciona mejor si se trata como una superficie medible. Guarda una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trata esta etapa como un contrato entre entradas y salidas validadas. Nombra los artefactos, define comprobaciones de éxito y no aceptes finalizaciones parciales silenciosas. Mantén el estado del grafo plano y tipado. Los blobs anidados ocultan qué nodo escribió cada campo y rompen la reanudación tras una interrupción.
Lista de comprobación operativa
Para la etapa «Lista de comprobación operativa», define las entradas, el responsable del paso y los criterios de salida antes de tocar el código. Los operadores deberían poder relanzar el paso desde un punto de control conocido sin adivinar estado oculto.
Documenta juntos el camino feliz y el de recuperación. Los reintentos, las aprobaciones humanas y la gestión de mensajes muertos forman parte del producto, no son un pulido para después.
Pon aprobación humana en las transiciones que gastan dinero o cambian datos de producción. Que todo esté conectado en tiempo de compilación no significa que el negocio esté completo.
Escribe un runbook breve: cómo rotar claves, cómo vaciar la cola y cómo revertir la última ingesta.
Mejor unidades pequeñas y comprobables que scripts kilométricos. Cuando un paso falla, el fallo debería señalar una única responsabilidad y no un pipeline enredado.
Pon aprobación humana en las transiciones que gastan dinero o cambian datos de producción. Que todo esté conectado en tiempo de compilación no significa que el negocio esté completo.
Antes de promocionar el stack, congela versiones, guarda una transcripción de referencia del camino crítico y confirma los pasos de reversión. Los entornos compartidos necesitan límites de peticiones, comprobaciones de multitenencia y un responsable claro de la rotación de secretos. Mejor una fiabilidad aburrida que demos ingeniosas de un solo uso.
Nota del lote 2e4d73bb1bc8: deja las claves de los proveedores fuera del repositorio, fija un tope de tokens por sesión y guarda las transcripciones junto a los fixtures de evaluación para que los futuros cambios de modelo sigan siendo comparables.