Engenharia de integração com IA em primeiro lugar usando Claude Code: uma sessão de depuração real

A maioria das histórias de "IA escreveu meu código" são demonstrações com instruções claras e resultados perfeitos. Esta é diferente. Esta é uma sessão real em um produto de integração APIANT real, incluindo as instruções reais, os erros, as correções e o momento em que a memória humana superou a máquina.

A questão não é que a IA seja impressionante. A questão é como a colaboração realmente se parece quando você se senta e realiza o trabalho.

A configuração

O produto é uma das nossas integrações do CRMConnect. Do Mindbody para o HubSpotUm cliente relatou que as vendas pagas com mais de um método de pagamento estavam sendo sincronizadas incorretamente. Uma venda de US$ 8.400, dividida em três métodos de pagamento, aparecia no HubSpot como um único negócio de US$ 400. Os outros US$ 8.000 estavam faltando no pipeline.

Acompanhamos o trabalho de engenharia no GitHub Issues. A conversa com o cliente ocorre no HubSpot Service Hub. A sessão começou com o desenvolvedor apontando a IA para o trabalho.

Incitar: “analise a questão do pagamento”

A IA pesquisou os problemas relatados no GitHub do repositório, encontrou o incidente aberto, extraiu todo o conteúdo e o leu em voz alta: um bug de vendas com múltiplos pagamentos, com dois IDs de execução em produção citados como evidência. Sem necessidade de instruções detalhadas. Em seguida, solicitou o próximo passo em termos simples, em vez de tentar adivinhar.

Incitar: “Qual é a lógica utilizada e quais são as automações/ações?”

A IA carregou a automação relevante da plataforma, analisou sua estrutura passo a passo e explicou a falha com precisão. A automação cria uma chave de desduplicação para cada negócio do HubSpot. Para vendas com múltiplos métodos de pagamento, o Mindbody retorna uma linha por método de pagamento, todas compartilhando a mesma chave; portanto, as linhas dois e três entraram em conflito com o negócio criado pela linha um e seus valores foram descartados silenciosamente.

Útil. Mas o construtor já tinha uma vantagem maior.

A dica que redirecionou tudo.

Incitar: “Compare este identificador único para o acordo com a forma como o fazemos no projeto crmconnect-mindbody-zoho. Pensei que tínhamos resolvido o problema lá. Faça uma comparação minuciosa.”

Essa única frase mudou completamente o rumo da obra. O construtor não descreveu uma solução. Ele apontou para um produto similar e disse, em resumo, para ir lê-lo.

Então a IA fez isso. Ela abriu o Do Mindbody para o Zoho A integração, um produto completamente separado, localizou a automação que lida com o histórico de vendas e a leu. Em seguida, encontrou e leu a sub-rotina que registra os pagamentos. Não resumos. A lógica de automação propriamente dita, passo a passo.

A resposta veio com uma comparação precisa. A integração com o Zoho de fato resolveu o problema, mas com uma arquitetura diferente:

• O produto da HubSpot registra um negócio único por linha de venda, usando o endpoint de vendas antigo da Mindbody, que retorna linhas de pagamento pré-divididas.
• O produto Zoho cria um registro de compra principal, além de registros filhos separados para itens de linha e para pagamentos, usando o endpoint mais recente do Mindbody, onde cada pagamento possui seu próprio ID de pagamento real.

A análise da IA concluiu que o Zoho tinha uma arquitetura mais limpa e, inicialmente, propôs migrar todo o modelo de três objetos para o HubSpot.

O construtor recua o escopo.

Era aqui que o ser humano mantinha as coisas com os pés no chão.

Incitar: “Ainda não está pronto para a versão 4.0. Deixe para depois, agora precisamos corrigir os problemas com as ofertas ausentes relatadas pelo cliente.”

A IA havia se aproximado de uma reformulação arquitetônica satisfatória. O desenvolvedor, então, voltou ao problema real: o cliente precisa dos valores corretos das transações, não de um novo modelo de dados. A IA concordou, encerrou a proposta de reformulação como um item futuro e redefiniu o escopo para uma correção cirúrgica nas automações de transações existentes.

Essa correção é importante. A IA é boa em encontrar a solução geral elegante. Mas nem sempre é boa em saber quando a solução elegante é mais do que o momento exige. O desenvolvedor forneceu esse julgamento em uma única frase.

A IA então adaptou o princípio por trás do design da Zoho, sem copiar sua estrutura: conciliar um negócio por item de venda, obter os dados do endpoint mais completo da Mindbody e agregar o valor corretamente entre os métodos de pagamento, em vez de deixar o primeiro pagamento sobrescrever os demais. Plataforma diferente, ações diferentes, mesma ideia subjacente.

A intuição

Ao reformular a chave de desduplicação, a IA analisou um de seus componentes: uma data. Seu raciocínio foi claro. O ID da venda e o ID do detalhe da venda já tornam a chave única. A data é redundante. A IA recomendou removê-la para simplificar a chave e eliminar uma fonte de fragilidade entre as duas automações.

O construtor não tinha um código de referência para discutir. Ele tinha memória.

Incitar: "Lembro-me de ter adicionado a data porque era necessário (dois pagamentos na mesma transação, ou algo estranho assim)?"

Nenhum dos dois conseguiu comprovar isso com a automação atual. Então, a IA acessou o histórico de versões da automação. A automação tinha noventa e três versões salvas, remontando a 2021. A IA leu as descrições das alterações até encontrar as relevantes.

A partir de janeiro de 2022:

“Adicionado EPOCH MILLIS para salvar o ID da transação no banco de dados e mantê-lo único quando vários pagamentos forem feitos no mesmo item”

A partir de fevereiro de 2022:

“Adicionada a data da venda para a função ‘Buscar negócio’ por propriedade personalizada, para que os pagamentos de vendas anteriores sejam processados automaticamente.”

Lá estava, nas palavras do próprio construtor, quatro anos antes. Quando um cliente faz um pagamento posterior referente a uma venda anterior, o Mindbody reemite essa venda na nova data. Sem a data na chave, o pagamento posterior entra em conflito com o negócio original e não consegue ser registrado separadamente. A data não era redundante. Era essencial, adicionada propositalmente para lidar com pagamentos parcelados e débitos automáticos.

A resposta da IA foi reverter sua recomendação imediatamente e deixar isso bem claro:

“Confie na sua memória. Se você adicionou a data deliberadamente, ela é essencial e removê-la está fora de questão. Encontrei-a no histórico de versões.”

A tarefa foi além. Como a data precisava ser mantida, as duas automações precisavam gerar exatamente o mesmo valor de data, caso contrário, as chaves não corresponderiam e negócios duplicados apareceriam. A automação original obtém a data a partir de um campo específico do Mindbody. A IA redirecionou a nova automação para ler esse mesmo campo, a partir da mesma chamada de API, com a mesma conversão de fuso horário. Mesma entrada, mesma saída, chaves garantidamente correspondentes.

Uma regressão que teria silenciosamente comprometido o processamento de pagamentos parcelados nunca ocorreu. Não porque a IA fosse cuidadosa, mas porque um humano se lembrou de uma intuição e a IA conseguiu verificá-la em segundos, comparando-a com quatro anos de histórico.

A parte pouco glamorosa: compilar, executar, ler o rastreamento, corrigir

Com o projeto definido, o processo tornou-se iterativo. Implementava-se a alteração em um ambiente de desenvolvimento, executava-se, lia-se o rastreamento da execução, encontrava-se o próximo problema, corrigia-se e executava-se novamente. Os bugs reais eram comuns:

• Uma etapa de criação de acordo falhou com dezesseis PROPERTY_DOESNT_EXIST Os erros ocorriam porque as associações de campo não continham os nomes de propriedade internos do HubSpot. A IA leu o rastreamento, obteve o esquema de campo do conector e reatribuiu a associação de cada campo com seu ID correto.
• Um loop foi executado duas vezes quando deveria ter sido executado apenas uma, porque a plataforma estava contando as iterações a partir do array mais longo nos dados de origem, e o array de pagamentos era maior que o array de itens de linha. A IA inseriu um controle de iteração explícito para que o loop contasse apenas os itens de linha.
• Uma etapa de "encontrar negócio" interrompeu toda a execução quando nenhum negócio foi encontrado ainda, porque seu modo de erro padrão tratava "não encontrado" como fatal. A IA alterou para "continuar em caso de erro" para que a criação da ramificação pudesse ser executada, correspondendo à forma como a automação irmã já lidava com isso.

Nada disso é glamoroso. É a realidade do trabalho de integração. O que mudou foi a velocidade do ciclo. A IA conseguia ler um rastreamento completo da execução passo a passo e apontar imediatamente para a etapa com falha, então cada ciclo de correção levava apenas alguns minutos. Nada era enviado ao cliente até que os testes de desenvolvimento fossem aprovados.

O que isso significa para os construtores

Removendo a narrativa, eis o modelo funcional:

• O ponto forte da IA é a leitura. A equipe estudou a integração completa de sistemas irmãos, analisou um problema que já havíamos resolvido, adaptou uma arquitetura para duas plataformas diferentes e vasculhou noventa versões do histórico para verificar uma decisão de projeto. Nenhum ser humano faz isso em uma tarde.
• A força do ser humano reside na memória e no discernimento. A frase “Acho que adicionei isso por um motivo” não consta em nenhum arquivo. A frase “Ainda não está pronto para a versão 4.0” também não consta em nenhum arquivo. Ambas as afirmações surgiram da experiência prática com o produto. Cada uma delas alterou o resultado final.
• A velocidade vem do laço. Leia o rastreamento, corrija a etapa e execute novamente. O atrito que normalmente atrasa a depuração e a reconstrução do que aconteceu desaparece.

A engenharia de integração com foco em IA não se resume à IA trabalhando sozinha, nem ao humano trabalhando mais rápido. Trata-se da IA realizando a leitura que nenhum humano tem tempo para fazer, e do humano fornecendo o contexto que nenhum registro de código existe. Junte esses dois elementos e um bug recorrente de quatro anos será compreendido, corrigido e verificado em uma única sessão de trabalho.

Esse é o fluxo de trabalho que vale a pena buscar.