Como pensei em economizar meu tempo de vida implantando VTEX

Recebemos aqui na Uncode o desafio de reestruturar uma loja FastStore, migrando do VTEX IO. Eu trabalhei com VTEX e e-commerces no geral por muito tempo na minha carreira, então fiquei pensando: por que não automatizar essa criação?

E de fato tinham muitos “porquês não”: desde a viabilização do produto acontecer até barreiras da própria plataforma, APIs e conhecimentos que a LLM não teria. Então seria um pouco difícil pensar em como ter uma arquitetura sólida para esse trabalho autônomo e programático.

O gargalo real não era código, era paridade.

O fluxo mais simples, por incrível que pareça, foi o desenho da arquitetura da squad e dos responsáveis, e as viabilizações que tivemos que fazer dados os desafios que foram aparecendo por ser um fluxo de plataforma. O mais complicado acabou sendo a paridade com o site original, porque ele tinha algumas peculiaridades do IO e muitos componentes customizados. Então a gente tinha que chegar num meio-termo, respeitando bastante o Lighthouse e as métricas de performance do FastStore mesmo com esses detalhes.

Transformei o trabalho repetitivo num loop fechado de agents.

Quatro papéis:

Validator <> Orquestrado <> VTEX Developer <> Quality Assurance

Eu acabei deixando o Claude Code fazendo esse papel. Quis aproveitar ele por conta do harness: ele tem diversas métricas de long session e loop. Então aproveitei essas ferramentas built-in, e isso acabou viabilizando o trabalho muito mais rápido.

A regra que mudou tudo: “fez uma vez, codifica”.

Todo fix ad-hoc virava agent, skill ou script reusável. Foi o que me fez extrair a squad pra um repo próprio. Hoje qualquer storefront FastStore novo herda o flow inteiro de graça. Aqui a gente olhou muito para a questão de single responsibility, de entender que a squad não pertence à entidade da FastStore, mas sim que ela tem um trabalho em cima da FastStore. Então ela acaba tendo uma codependência, porém existem outros mecanismos que desacoplam esse atrito, porque com acoplamento qualquer fix de um produto em crescimento como o FastStore quebraria o trabalho.

Separei o que deploya do que ajuda a deployar.

Storefront slim e deployável de um lado; squad agentic, scripts de QA e docs de outro. Ligados por symlink, nunca misturados.

O fluxo hoje é automatizado de ponta a ponta, desde a implementação até a parte de upload do CMS. Então, mesmo sem API (pelo menos eu não encontrei), eu peguei as chamadas ali mesmo do navegador e coloquei isso meio que built-in também na squad. Na squad a gente também tem um agente responsável por fazer a manutenção do CMS do cliente.

Classificar mismatch é mais valioso que detectar.

Nem todo diff é bug: SKU, preço e hero dinâmico são ruído justificável. Header, gap, fonte e padding sistemático são estruturais. O agent que sabe a diferença economiza horas de caça a falso positivo.

E o mais interessante dessa abordagem de olhar pro mismatch, que é a porcentagem realmente sistêmica, a real da disparidade, é que muitas vezes o próprio squad conseguia justificar o mismatch por métricas de SEO, por métricas de performance, ou por ser algo nativo que tinha que ser usado daquela forma e não mudaria muita coisa. Então foi muito legal ver a forma com que o squad foi entendendo essas coisas com o tempo.

Root-cause acima de bypass, sempre.

Um exemplo aqui foi o loop de ValidateCartMutation. Ele não se resolve removendo hook nem com patch-package. Mede request, response, IndexedDB e eventos primeiro. Pressa aqui custa dias depois.

E o ponto que mais liga ao harness aqui é a ansiedade do modelo. O squad, por diversas vezes, só quer te entregar aquilo para te satisfazer, para conseguir fechar o assunto, mas acaba não olhando o todo. Por isso acaba sendo importante a engenharia de harness para conseguir punir esse tipo de atitude, entender quais são os triggers, quais são os gatilhos que fazem ele começar a seguir por esse caminho, e remediar com hooks, rules ou skills.

Medir antes de editar virou reflexo.

Nossa, muitas vezes dava vontade só de fazer um patch no node_modules direto e corrigir algumas coisas que a gente julga erradas na VTEX. Mas depois de pesquisar bastante, olhar as issues, o que tem de aberto, deu pra entender muitos pontos da jornada de desenvolvimento da VTEX e do FastStore também. Os porquês e como se chegou naquilo. Acabou sendo mais resiliente, e a gente chegou no resultado que chegou graças a bastante dessa ótica.

Self-learning é o que mantém a cadeia viva.

Esse foi o ponto que mais importou, e talvez o menos óbvio.

Uma squad agentic que não aprende vira um pipeline engessado: na primeira mudança de versão do FastStore, ou numa peculiaridade nova do cliente, ela quebra e te dá mais trabalho do que faz. O que desacopla a cadeia desse modo travado de pensar é o ciclo de aprendizado. Cada erro corrigido, cada mismatch justificado, cada gotcha de plataforma que a gente descobriu vira memória durável e volta pro fluxo como rule, skill ou hook e em instancia maior para um RAG.

Então a squad não está presa à tecnologia atual nem a um jeito fixo de resolver: ela melhora a si mesma a cada sessão. É isso que faz o custo de onboard do próximo cliente cair em vez de subir, e o que faz a paridade de hoje não virar a dívida técnica de amanhã.