Ingeniería de integración centrada en la IA con Claude Code: una sesión de depuración real

La mayoría de las historias de "la IA escribió mi código" son demostraciones con una consigna clara y un resultado impecable. Este no es el caso. Se trata de una sesión real con un producto de integración APIANT real, incluyendo las consignas reales, los errores, las correcciones y el momento en que la memoria humana superó a la máquina.

La cuestión no es que la IA sea impresionante. La cuestión es cómo se ve realmente la colaboración cuando uno se sienta a trabajar.

La configuración

El producto es una de nuestras integraciones de CRMConnect, Mindbody a HubSpotUn cliente informó que las ventas pagadas con más de un método de pago no se sincronizaban correctamente. Una venta de $8,400 dividida entre tres métodos de pago aparecía en HubSpot como una sola transacción de $400. Los otros $8,000 no figuraban en el embudo de ventas.

Hacemos un seguimiento del trabajo de ingeniería en GitHub Issues. La conversación con el cliente se encuentra en HubSpot Service Hub. La sesión comenzó cuando el desarrollador le indicó a la IA el trabajo a realizar.

Inmediato: “analicen el problema del pago”

La IA buscó en los problemas de GitHub del repositorio, encontró el incidente abierto, extrajo el texto completo y lo leyó: un error de ventas con múltiples pagos, con dos identificadores de ejecución de producción citados como evidencia. No necesitó ayuda. Luego, preguntó cuál era el siguiente paso en términos sencillos, en lugar de adivinar.

Inmediato: “¿Qué hace la lógica y qué automatizaciones/acciones?”

La IA cargó la automatización correspondiente desde la plataforma, analizó su estructura paso a paso y explicó el fallo con precisión. La automatización crea una clave de deduplicación para cada transacción de HubSpot. En el caso de ventas con múltiples métodos de pago, Mindbody devuelve una fila por método de pago, todas con la misma clave, por lo que las filas dos y tres se superponían con la transacción creada por la fila uno y sus importes se descartaban automáticamente.

Útil. Pero el constructor ya tenía una ventaja mayor.

La pista que lo redirigió todo

Inmediato: “Compara este identificador único para el acuerdo con cómo lo hacemos en el proyecto crmconnect-mindbody-zoho. Creí que lo habíamos resuelto. Haz una comparación muy precisa.”

Esta simple frase cambió el rumbo de la obra. El constructor no describió una solución. Señaló un producto similar y, en esencia, dijo: «Vayan a leerlo».

Así lo hizo la IA. Abrió el De la mente al cuerpo Zoho La integración, un producto completamente independiente, localizó la automatización que gestiona el historial de ventas y la leyó. Luego, encontró y leyó la subrutina que registra los pagos. No los resúmenes. La lógica de automatización propiamente dicha, paso a paso.

El resultado fue una comparación detallada. La integración con Zoho sí había resuelto el problema, pero con una arquitectura diferente:

• El producto de HubSpot registra una única transacción por línea de venta, utilizando el antiguo punto final de ventas de Mindbody, que devuelve filas de pago predivididas.
• El producto Zoho crea un registro de compra principal, además de registros secundarios separados para los artículos y los pagos, utilizando el punto final más reciente de Mindbody, donde cada pago lleva su propio ID de pago real.

La IA concluyó que Zoho tenía una arquitectura más limpia y, en un principio, propuso trasladar todo el modelo de tres objetos a HubSpot.

El constructor reduce el alcance del proyecto.

Aquí es donde el ser humano mantenía las cosas con los pies en la tierra.

Inmediato: “Aún no estamos listos para la versión 4.0. La dejaremos para más adelante; ahora necesitamos solucionar los problemas con las ofertas que faltan, según lo reportado por los clientes.”

La IA se había encaminado hacia una reescritura arquitectónica satisfactoria. El desarrollador la centró en el problema real: el cliente necesita importes de transacción correctos, no un nuevo modelo de datos. La IA estuvo de acuerdo, archivó la propuesta de reescritura como un tema futuro y reorientó el alcance hacia una solución precisa para las automatizaciones de transacciones existentes.

Esa corrección es importante. La IA es buena para encontrar la solución general elegante. No siempre es buena para saber cuándo la solución elegante es más de lo que la situación requiere. El desarrollador expresó ese juicio en una sola frase.

La IA adaptó el principio de diseño de Zoho, sin copiar su estructura: conciliar una transacción por cada artículo de venta, obtener los datos del punto final más completo de Mindbody y agregar correctamente el importe entre los distintos métodos de pago, en lugar de permitir que el primer pago sobrescriba el resto. Plataforma diferente, acciones diferentes, misma idea subyacente.

La corazonada

Al revisar la clave de deduplicación, la IA analizó uno de sus componentes: la fecha. Su razonamiento fue claro. El ID de venta y el ID de detalle de venta ya hacen que la clave sea única. La fecha es redundante. Recomendó eliminarla para simplificar la clave y eliminar una fuente de vulnerabilidad entre las dos automatizaciones.

El constructor no tenía ninguna referencia de código con la que discutir. Tenía memoria.

Inmediato: “Creo recordar que añadí la fecha porque era necesaria (dos pagos en la misma transacción, o algo raro por el estilo).”

Ninguno de los dos pudo demostrarlo a partir de la automatización actual. Así que la IA consultó el historial de versiones de la automatización. Esta tenía noventa y tres versiones guardadas, que se remontaban a 2021. La IA leyó las descripciones de los cambios hasta encontrar las relevantes.

Desde enero de 2022:

“Se agregó EPOCH MILLIS al guardado del ID de transacción en la base de datos para mantenerlo único cuando se realizan múltiples pagos por el mismo artículo”.

Desde febrero de 2022:

“Se agregó la fecha de venta para buscar ofertas por propiedad personalizada, de modo que procese los pagos de ventas anteriores”.

Ahí estaba, en palabras del propio constructor, cuatro años antes. Cuando un cliente realiza un pago posterior a una venta anterior, Mindbody vuelve a emitir esa venta en la nueva fecha. Sin la fecha en la clave, el pago posterior entra en conflicto con la transacción original y no puede obtener su propio registro. La fecha no era redundante. Era un elemento fundamental, añadido deliberadamente para gestionar los pagos a plazos y los pagos automáticos.

La respuesta de la IA fue retractarse de su recomendación de inmediato y decirlo claramente:

“Confía en mi recuerdo. Si añadiste la fecha deliberadamente, es un elemento determinante, y eliminarla ya no sirve. La encontré en el historial de versiones.”

Luego, la cosa fue más allá. Dado que la fecha debía permanecer invariable, las dos automatizaciones debían generar el mismo valor de fecha; de lo contrario, las claves no coincidirían y aparecerían ofertas duplicadas. La automatización original obtiene la fecha de un campo específico de Mindbody. La IA reorientó la nueva automatización para que leyera ese mismo campo, mediante la misma llamada a la API y con la misma conversión de zona horaria. Misma entrada, misma salida, claves que coinciden garantizadamente.

Nunca se produjo una regresión que hubiera afectado silenciosamente la gestión de pagos a plazos. No porque la IA fuera cuidadosa, sino porque un humano recordó una intuición y la IA pudo verificarla en segundos con cuatro años de historial.

La parte menos glamurosa: construir, ejecutar, leer el registro de errores, corregir

Una vez definido el diseño, se pasó a la ingeniería iterativa. Se implementaba el cambio en un entorno de desarrollo, se ejecutaba, se leía el registro de ejecución, se encontraba el siguiente problema, se corregía y se volvía a ejecutar. Los errores reales eran comunes:

• Un paso para crear un acuerdo fracasó con dieciséis PROPERTY_DOESNT_EXIST Se produjeron errores porque las vinculaciones de campos no contenían los nombres de propiedades internas de HubSpot. La IA leyó el registro, recuperó el esquema de campos del conector y volvió a vincular cada campo con su ID correcto.
• El bucle se ejecutó dos veces cuando debería haberse ejecutado una sola vez, porque la plataforma contaba las iteraciones a partir del array más largo de los datos de origen, y el array de pagos era más largo que el array de artículos. La IA insertó un control de iteración explícito para que el bucle contara solo los artículos.
• Un paso de “búsqueda de ofertas” detuvo toda la ejecución cuando aún no existía ninguna oferta, porque su modo de error predeterminado consideraba “no encontrado” como un error fatal. La IA lo cambió a continuar en caso de error para que la rama de creación pudiera ejecutarse, de forma similar a como lo había gestionado la automatización hermana.

Nada de esto es glamuroso. Es la cruda realidad del trabajo de integración. Lo que cambió fue la velocidad del ciclo. La IA podía leer un registro completo de la ejecución paso a paso e identificar el paso que fallaba de inmediato, por lo que cada ciclo de corrección duraba minutos. No se enviaba nada al cliente hasta que las pruebas de desarrollo se superaban con éxito.

¿Qué significa esto para los constructores?

Si eliminamos la narrativa, este es el modelo de trabajo:

• La fortaleza de la IA reside en la lectura. Estudió la integración completa de dos hermanos, contrastó un problema que ya habíamos resuelto, adaptó una arquitectura a dos plataformas diferentes y examinó noventa versiones del historial para verificar una decisión de diseño. Ningún ser humano hace eso en una tarde.
• La fortaleza del ser humano reside en la memoria y el juicio. “Creo que lo añadí por alguna razón” no aparece en ningún archivo. “Aún no está listo para la versión 4.0” tampoco aparece en ningún archivo. Ambas ideas surgieron de haber usado el producto. Cada una cambió el resultado.
• La velocidad proviene del bucle. Lee el registro de errores, corrige el paso y vuelve a ejecutar. La dificultad que suele ralentizar la depuración y la reconstrucción de lo sucedido desaparece.

La ingeniería de integración centrada en la IA no consiste en que la IA trabaje sola, ni en que el humano trabaje más rápido. Consiste en que la IA realice la lectura que ningún humano tiene tiempo de hacer, y el humano proporcione el contexto que no se encuentra en los registros del código fuente. Al combinar ambos elementos, un error recurrente de cuatro años se comprende, se corrige y se verifica en una sola sesión de trabajo.

Ese es el flujo de trabajo que vale la pena construir.