Ingegneria dell'integrazione incentrata sull'IA con Claude Code: una vera sessione di debug

La maggior parte delle storie del tipo "L'IA ha scritto il mio codice" sono dimostrazioni con un prompt pulito e un risultato pulito. Questa è diversa. Questa è una vera sessione su un vero prodotto di integrazione APIANT, inclusi i prompt effettivi, gli errori, le correzioni e il momento in cui la memoria umana ha avuto la meglio sulla macchina.

Il punto non è che l'IA sia impressionante. Il punto è come si presenta concretamente la collaborazione quando ci si siede e si mette al lavoro.

La configurazione

Il prodotto è una delle nostre integrazioni CRMConnect, Da Mindbody a HubSpotUn cliente ha segnalato che le vendite pagate con più di un metodo di pagamento non venivano sincronizzate correttamente. Una vendita di 8.400 dollari, suddivisa tra tre metodi di pagamento, risultava in HubSpot come un'unica transazione da 400 dollari. Gli altri 8.000 dollari non erano presenti nel flusso di vendita.

Monitoriamo il lavoro di ingegneria su GitHub Issues. La conversazione con il cliente si svolge su HubSpot Service Hub. La sessione è iniziata con lo sviluppatore che ha indicato all'IA il lavoro da svolgere.

Richiesta: “esamina la questione del pagamento”

L'IA ha cercato tra i problemi di GitHub del repository, ha trovato l'incidente aperto, ha estratto il corpo completo e lo ha letto: un bug relativo alle vendite con pagamenti multipli, con due ID di esecuzione in produzione citati come prova. Non è stato necessario alcun aiuto. Ha quindi chiesto il passo successivo in termini chiari, invece di fare supposizioni.

Richiesta: “Qual è la funzione logica e quali automazioni/azioni sono necessarie?”

L'IA ha caricato l'automazione pertinente dalla piattaforma, ne ha analizzato la struttura passo dopo passo e ha spiegato con precisione l'errore. L'automazione crea una chiave di deduplicazione per ogni trattativa di HubSpot. Per le vendite con pagamenti multipli, Mindbody restituisce una riga per ogni metodo di pagamento, tutte con la stessa chiave, quindi le righe due e tre sono entrate in conflitto con la trattativa creata dalla riga uno e i relativi importi sono stati scartati silenziosamente.

Utile. Ma il costruttore aveva già un vantaggio maggiore.

Il suggerimento che ha reindirizzato tutto

Richiesta: "Confronta questo identificativo univoco per l'accordo con il modo in cui lo gestiamo nel progetto crmconnect-mindbody-zoho. Pensavo che avessimo risolto il problema lì. Fai un confronto estremamente preciso."

Questa singola frase ha cambiato la natura dell'opera. Il costruttore non ha descritto una soluzione. Ha indicato un prodotto simile e ha detto, in sostanza, di andarlo a leggere.

Quindi l'IA lo ha fatto. Ha aperto il Da Mindbody a Zoho L'integrazione, un prodotto completamente separato, ha individuato l'automazione che gestisce le vendite storiche e l'ha letta. Poi ha trovato e letto la subroutine che scrive i record di pagamento. Non i riepiloghi. La logica di automazione vera e propria, passo dopo passo.

Il risultato è stato un confronto mirato. L'integrazione con Zoho aveva effettivamente risolto il problema, ma con un'architettura diversa:

• Il prodotto HubSpot crea un unico ordine fisso per ogni riga di vendita, utilizzando il vecchio endpoint di vendita di Mindbody, che restituisce righe di pagamento pre-suddivise.
• Il prodotto Zoho crea un record di acquisto principale più record secondari separati per le singole voci e per i pagamenti, utilizzando il nuovo endpoint di Mindbody, in cui ogni pagamento ha il proprio ID di pagamento reale.

L'intelligenza artificiale ha concluso che Zoho avesse un'architettura più pulita e inizialmente ha proposto di trasferire l'intero modello a tre oggetti in HubSpot.

Il costruttore ritira il cannocchiale

È qui che l'essere umano ha mantenuto i piedi per terra.

Richiesta: "Non siamo ancora pronti per la versione 4.0. Rimandiamola a più tardi, ora dobbiamo risolvere i problemi relativi alle offerte mancanti segnalati dal cliente."

L'IA si era orientata verso una riscrittura architetturale soddisfacente. Lo sviluppatore è tornato al problema reale: il cliente necessita di importi corretti per le transazioni, non di un nuovo modello di dati. L'IA ha acconsentito, ha archiviato la proposta di riscrittura come elemento futuro e ha ridefinito l'ambito del progetto per una correzione mirata delle automazioni esistenti relative alle transazioni.

Quella correzione è importante. L'IA è brava a trovare la soluzione generale più elegante. Non sempre, però, riesce a capire quando la soluzione più elegante è eccessiva rispetto a quanto richiesto dal momento. Il costruttore ha espresso questo giudizio in una sola frase.

L'IA ha quindi adattato il principio alla base del design di Zoho, senza però copiarne la struttura: riconciliare una transazione per ogni voce di vendita, acquisire i dati dall'endpoint più completo di Mindbody e aggregare correttamente l'importo tra i diversi metodi di pagamento, anziché lasciare che il primo pagamento sovrascriva gli altri. Piattaforma diversa, azioni diverse, stessa idea di base.

L'intuizione

Durante la rielaborazione della chiave di deduplicazione, l'IA ha analizzato uno dei suoi componenti: una data. Il suo ragionamento era chiaro. L'ID della vendita e l'ID del dettaglio della vendita rendono già la chiave univoca. La data è ridondante. Ha raccomandato di eliminarla per semplificare la chiave ed eliminare una fonte di fragilità tra le due automazioni.

Il costruttore non aveva un codice di riferimento con cui discutere. Aveva la memoria.

Richiesta: "Mi sembra di ricordare di aver aggiunto la data perché era necessaria (due pagamenti nella stessa transazione, o qualcosa di strano del genere)?"

Nessuno dei due è riuscito a dimostrarlo con l'automazione attuale. Quindi l'IA ha esaminato la cronologia delle versioni dell'automazione. L'automazione aveva novantatré versioni salvate, risalenti al 2021. L'IA ha letto le descrizioni delle modifiche fino a trovare quelle pertinenti.

A partire da gennaio 2022:

"Aggiunto EPOCH MILLIS all'ID transazione salvato nel database per mantenerlo univoco quando vengono effettuati più pagamenti sullo stesso articolo."

A partire da febbraio 2022:

"Aggiunta la data di vendita per la ricerca dell'affare tramite proprietà personalizzata, in modo che elabori i pagamenti relativi alle vendite precedenti."

Eccolo lì, per usare le parole del costruttore, quattro anni prima. Quando un cliente effettua un pagamento successivo a una vendita precedente, Mindbody riemette la vendita alla nuova data. Senza la data nella chiave, il pagamento successivo si sovrappone all'accordo originale e non può essere registrato separatamente. La data non era superflua. Era un elemento portante, aggiunto appositamente per gestire i pagamenti rateali e automatici.

La risposta dell'IA è stata quella di ribaltare immediatamente la sua raccomandazione e di dirlo chiaramente:

“Fidati di quel ricordo. Se hai aggiunto la data intenzionalmente, è un elemento portante e rimuoverla non è possibile. L'ho trovata nella cronologia delle versioni.”

Si è poi andati oltre. Poiché la data doveva rimanere invariata, le due automazioni dovevano produrre esattamente lo stesso valore di data, altrimenti le chiavi non sarebbero corrisposte e sarebbero apparse offerte duplicate. L'automazione originale ricava la data da uno specifico campo di Mindbody. L'IA ha riorientato la nuova automazione in modo che leggesse lo stesso identico campo, dalla stessa chiamata API, con la stessa conversione di fuso orario. Stesso input, stesso output, chiavi garantite per corrispondere.

Un problema che avrebbe potuto compromettere silenziosamente la gestione dei pagamenti rateali non si è mai verificato. Non perché l'IA fosse stata particolarmente attenta, ma perché un essere umano ha avuto un'intuizione e l'IA è stata in grado di verificarla in pochi secondi confrontandola con i dati storici degli ultimi quattro anni.

La parte meno affascinante: costruire, eseguire, leggere la traccia, correggere

Una volta definito il progetto, si passò all'ingegneria iterativa. Si implementava la modifica in un ambiente di sviluppo, la si eseguiva, si leggeva la traccia di esecuzione, si individuava il problema successivo, lo si risolveva e si rieseguiva. I veri bug erano quelli comuni:

• Una fase di creazione dell'accordo è fallita con sedici PROPERTY_DOESNT_EXIST Gli errori si verificavano perché i collegamenti dei campi non riportavano i nomi delle proprietà interne di HubSpot. L'IA ha letto la traccia, ha recuperato lo schema dei campi del connettore e ha ricollegato ogni campo con il suo ID corretto.
• Il ciclo è stato eseguito due volte anziché una sola, perché la piattaforma contava le iterazioni sull'array più lungo nei dati di origine, e l'array dei pagamenti era più lungo dell'array delle singole voci. L'IA ha inserito un controllo esplicito delle iterazioni in modo che il ciclo contasse solo le singole voci.
• Un passaggio di "ricerca offerta" ha bloccato l'intera esecuzione quando non esisteva ancora alcuna offerta, perché la sua modalità di errore predefinita considerava "non trovato" come fatale. L'IA l'ha quindi commutata in "continua in caso di errore" in modo che il ramo di creazione potesse essere eseguito, replicando il modo in cui l'automazione correlata gestiva già la situazione.

Niente di tutto ciò è affascinante. È la realtà del lavoro di integrazione. Ciò che è cambiato è la velocità del ciclo. L'IA era in grado di leggere una traccia di esecuzione completa passo passo e individuare immediatamente il passaggio fallimentare, quindi ogni ciclo di correzione durava pochi minuti. Nulla veniva rilasciato al cliente finché i test di sviluppo non venivano superati.

Cosa significa questo per i costruttori

Eliminando la narrazione, ecco il modello di lavoro:

• Il punto di forza dell'IA è la lettura. Ha studiato un'intera integrazione tra sistemi fratelli, ha confrontato un problema che avevamo già risolto, ha adattato un'architettura a due piattaforme diverse e ha vagliato novanta versioni storiche per verificare una singola decisione progettuale. Nessun essere umano farebbe una cosa del genere in un pomeriggio.
• La forza dell'essere umano risiede nella memoria e nella capacità di giudizio. “Penso di averlo aggiunto per un motivo” non è presente in nessun file. “Non ancora pronto per la versione 4.0” non è presente in nessun file. Entrambe derivano dall'esperienza diretta con il prodotto. Ognuna ha influenzato il risultato.
• La velocità deriva dal ciclo. Leggi la traccia, correggi il passaggio, riavvia. L'attrito che di solito rallenta il debug, la ricostruzione di ciò che è accaduto, è sparito.

L'ingegneria di integrazione basata sull'IA non significa che l'IA lavori da sola, né che l'essere umano lavori più velocemente. Significa che l'IA si occupa della lettura per cui nessun essere umano ha tempo, e l'essere umano fornisce il contesto che non è presente nel codice sorgente. Mettendo insieme questi due elementi, un bug ricorrente di quattro anni può essere compreso, corretto e verificato in un'unica sessione di lavoro.

Questo è il flusso di lavoro a cui vale la pena puntare.