Um site WordPress pode parecer estar funcionando normalmente para os visitantes, mesmo utilizando plugins com vários anos de existência, acumulando sobrecarga desnecessária no banco de dados ou ocultando problemas de compatibilidade que só aparecem em condições específicas.

Foi isso que descobrimos ao utilizar o Claude Code para investigar uma loja virtual WooCommerce com três anos de existência.

A loja estava funcionando, os produtos apareciam na loja, os clientes podiam navegar pelo catálogo e o tema existente era responsável pelo layout. No entanto, uma auditoria inicial revelou dependências desatualizadas, um plugin que preenchia os registros de erros com mensagens repetidas, uma atualização pendente do banco de dados do WooCommerce e um erro fatal de PHP na integração do tema com o Elementor.

Queríamos descobrir até que ponto a IA poderia modernizar o site sem reconstruí-lo ou comprometer suas funcionalidades existentes.

Utilizando o ambiente de teste da Kinsta, o Visual Studio Code via SSH e o Claude Code, investigamos os problemas, eliminamos atividades desnecessárias de plugins, atualizamos o tema e renovamos a aparência da loja virtual.

Veja como o processo funcionou, o que mudou e o que os desenvolvedores podem aprender com essa experiência ao realizar a manutenção de instalações antigas do WordPress.

Começando com uma loja virtual WordPress existente

Para este experimento, utilizamos uma loja de demonstração WordPress criada há vários anos para vender produtos de beleza e cuidados com os cabelos.

A loja virtual WooCommerce original antes da modernização assistida por IA.
A loja virtual WooCommerce original antes da modernização assistida por IA.

A loja virtual utiliza WooCommerce com Astra, Elementor, CartFlows e vários outros plugins que gerenciam desde a apresentação dos produtos até formulários de contato e a finalização de compras.

Essa é uma situação comum para agências que fazem a manutenção de sites WordPress existentes há algum tempo. Com o passar dos anos, os plugins se acumulam, o design original fica ultrapassado e as atualizações se tornam mais difíceis, pois alterar um componente pode afetar outro.

Não queríamos reconstruir o site nem substituir suas funcionalidades de eCommerce existentes. Nosso objetivo era entender o que poderíamos melhorar e implementar alterações gradualmente.

No início do experimento, a instalação no ambiente de teste apresentava a seguinte configuração:

Componente Versão ou estado
WordPress 7.1.4
PHP 8.2.35
Astra 4.1.5
Elementor 3.18.3
WooCommerce 8.5.5
CartFlows 2.1.5
Plugins ativos 15, sendo que 14 tinham atualizações disponíveis
Código personalizado de tema ou plugin Nenhum tema filho ou plugin personalizado encontrado

A ausência de código personalizado era importante. Não se tratava de um projeto em que poderíamos fornecer ao Claude uma classe PHP legada e solicitar a refatoração da implementação. A maior parte do comportamento do site dependia de plugins de terceiros e de suas configurações.

Isso significava que a modernização exigia compreender as dependências, verificar a compatibilidade e decidir quais componentes poderiam ser alterados sem afetar o restante do site.

Utilizando o Claude Code para auditar o site

Começamos nos conectando ao ambiente de teste da Kinsta via SSH pelo Visual Studio Code. Também instalamos a extensão Claude Code no VS Code e fizemos login, permitindo que o Claude inspecionasse os arquivos do WordPress, executasse comandos WP-CLI e investigasse diretamente a instalação.

Antes de realizar qualquer alteração, criamos um backup do ambiente de teste e registramos as configurações existentes do site, as respostas HTTP das páginas e os registros de erros para estabelecer uma referência inicial.

Claude inspecionando os arquivos do WordPress.
Claude inspecionando os arquivos do WordPress.

Depois de conectado, o Claude Code conseguiu inspecionar a instalação do WordPress, examinar os arquivos de temas e plugins e executar comandos no ambiente de teste.

Em vez de solicitar ao Claude que atualizasse o site imediatamente, começamos com uma auditoria somente de leitura:

Inspecione a instalação do WordPress e identifique dependências desatualizadas, código personalizado, possíveis problemas de compatibilidade, erros recorrentes e oportunidades de modernização gradual. Apresente evidências que sustentem cada descoberta e diferencie problemas confirmados de riscos potenciais. Não modifique arquivos, atualize plugins nem altere o banco de dados.

Isso gerou um inventário da instalação, mas as descobertas mais interessantes surgiram da análise dos registros de erros e do banco de dados.

Relatório do Claude após a auditoria do site.
Relatório do Claude após a auditoria do site.

O que a auditoria revelou

O Claude identificou vários problemas de manutenção que não eram evidentes ao navegar pela loja virtual.

Descoberta Evidência
Mensagens repetidas nos registros de erros O Starter Templates, um plugin para importar designs WordPress prontos, registrava repetidamente mensagens no registro de erros do PHP durante nossas solicitações de teste.
JavaScript desnecessário no frontend O Starter Templates carregava um script de pré-visualização de templates em páginas públicas.
Excesso de opções carregadas automaticamente Aproximadamente 2,9 MB de opções eram carregadas automaticamente, sendo que duas opções de dados de documentação representavam a maior parte desse total.
Manutenção pendente do WooCommerce A versão do banco de dados do WooCommerce armazenada era 7.7.0, enquanto a versão do plugin instalado era 8.5.5.
Tarefas em segundo plano com falha O CartFlows apresentava 122 falhas registradas em uma ação de atualização da base de conhecimento.
Dependências desatualizadas Vários plugins e o tema Astra estavam várias versões abaixo das versões mais recentes disponíveis.

Essas descobertas nos apresentaram várias possibilidades. Poderíamos atualizar tudo, mas isso dificultaria identificar qual alteração causou um problema. Também aumentaria o risco de afetar a finalização de compras, o CartFlows ou o conteúdo do Elementor.

Em vez disso, selecionamos um problema pequeno que poderíamos isolar e medir.

Eliminando atividades desnecessárias de plugins

O primeiro problema envolvia o Starter Templates, um plugin normalmente utilizado para importar designs WordPress prontos.

Nessa instalação, o plugin já havia cumprido sua finalidade original. A loja virtual estava pronta, e o importador não era necessário para exibir as páginas existentes.

No entanto, a versão instalada ainda executava código que gravava mensagens no registro de erros do PHP. O Claude rastreou essas mensagens até uma chamada em:

wp-content/plugins/astra-sites/inc/lib/class-astra-sites-zip-ai.php

A instrução responsável era:

error_log( $zip_ai_path );

A investigação revelou que a mesma mensagem correspondia a todas as 281 linhas dos cinco registros de erros analisados.

Claude identificando problemas no site WordPress.
Claude identificando problemas no site WordPress.

O plugin também colocava na fila de carregamento um arquivo JavaScript de 6,5 KB utilizado pela funcionalidade de pré-visualização de templates, inclusive em páginas comuns da loja virtual.

Nenhum dos dois problemas era catastrófico. No entanto, as mensagens repetidas tornavam os registros de erros menos úteis, enquanto o script no frontend não apresentava nenhuma finalidade aparente para os visitantes.

Escolhendo entre atualizar e desativar

Uma versão mais recente do Starter Templates removeu a instrução responsável pelo registro das mensagens. Portanto, uma atualização poderia ter resolvido essa parte do problema.

Uma análise mais detalhada mostrou que a versão mais recente ainda carregava o script de pré-visualização. Desativar o plugin eliminaria ambos os problemas. Antes de fazer essa alteração, o Claude verificou se outros plugins ou o tema ativo dependiam do Starter Templates durante a execução. Nenhuma dependência necessária para exibir a loja virtual existente foi encontrada.

Claude priorizando as etapas de modernização.
Claude priorizando as etapas de modernização.

Havia uma desvantagem: a desativação removeria a biblioteca do Starter Templates do Elementor e do Editor de Blocos. Isso seria relevante caso os editores ainda utilizassem a biblioteca para criar novas seções, embora as páginas existentes continuassem funcionando.

Depois de avaliar esse impacto, desativamos o Starter Templates no ambiente de teste por meio de MyKinsta > Sites > Plugins e temas.

Atualização de plugins WordPress no MyKinsta.
Atualização de plugins WordPress no MyKinsta.

Os resultados

Comparamos o ambiente de teste antes e depois da desativação.

Verificação Antes Depois
Novas entradas no registro de erros durante 10 solicitações sem cache 10 0
Script de pré-visualização do Starter Templates Carregado em 10 das 11 páginas testadas Não era mais carregado
Saída inesperada no WP-CLI Presente Eliminada
Códigos de status das respostas da loja virtual Referência inicial estabelecida Sem alterações
Conteúdo gerado pelo Elementor Referência inicial estabelecida Sem alterações

Os controles específicos do plugin no editor também desapareceram, conforme esperado. Essa foi nossa primeira melhoria comprovada, sem alterar os dados dos produtos da loja virtual, a configuração de finalização de compra ou o conteúdo das páginas existentes.

Isso também demonstrou por que a auditoria era importante. A solução não era escrever mais código, mas identificar um componente de que o site não precisava mais e eliminar suas atividades desnecessárias.

Corrigindo um erro de compatibilidade do PHP por meio da atualização do tema

Durante a investigação, Claude descobriu algo mais significativo. Uma solicitação anônima ao endpoint de configurações globais do Elementor retornava um erro HTTP 500:

/wp-json/elementor/v1/globals

O registro de erros do PHP apontava para o código de compatibilidade do tema Astra com o Elementor:

astra/inc/compatibility/class-astra-elementor.php

O erro foi:

Call to undefined method WP_Error::get_data()

O problema surgiu de uma suposição na implementação antiga do Astra. O endpoint do Elementor restringe o acesso com base nas permissões. Quando uma solicitação não possui as permissões necessárias, o WordPress pode retornar um objeto WP_Error.

Em seguida, a função de compatibilidade do Astra processa a resposta por meio do filtro rest_request_after_callbacks do WordPress. No Astra 4.1.5, o código tentava chamar get_data() sem verificar primeiro se a resposta era uma resposta REST bem-sucedida.

No entanto, WP_Error não disponibiliza esse método, fazendo com que a solicitação resultasse em um erro fatal de PHP.

Encontrando a correção sem modificar o tema manualmente

Pedimos ao Claude que comparasse a versão instalada do Astra com a versão mais recente disponível pelo WordPress. Ele identificou esta condição de proteção no Astra 4.14.1:

if ( is_wp_error( $response ) || ! $response instanceof \WP_REST_Response ) {
    return $response;
}

A condição verifica se o WordPress retornou um erro ou outro tipo de resposta inesperada antes de tentar acessar os dados da resposta REST.

Essa era a correção adequada para a falha que havíamos reproduzido. Poderíamos ter modificado diretamente o arquivo de compatibilidade do tema antigo, mas isso criaria uma alteração local no código de um tema de terceiros. Uma futura atualização do tema poderia sobrescrevê-la.

Em vez disso, optamos pela atualização oficial do Astra.

A atualização corrigiu o erro?

Sim, para as solicitações que reproduzimos.

Teste Astra 4.1.5 Astra 4.14.1
Solicitação anônima às configurações globais do Elementor HTTP 500 com erro fatal de PHP HTTP 401, rest_forbidden
Usuário autenticado sem a permissão necessária Erro fatal de PHP HTTP 403
Administrador autorizado HTTP 200 HTTP 200
Novos erros de PHP durante as verificações REST Erro fatal registrado Nenhum erro registrado

A solicitação anônima continuava sem acesso ao endpoint, como esperado. A diferença era que o WordPress retornava o erro de autorização adequado em vez de apresentar uma falha fatal.

Modernizando a loja virtual sem reconstruir o WooCommerce

Com o tema atualizado, voltamos nossa atenção para a aparência do site. O design original utilizava detalhes em azul do Astra, tipografia Lato, botões quadrados e uma grade básica de produtos do WooCommerce. Também exibia botões grandes para pedidos pelo WhatsApp que não combinavam com a identidade visual do site.

A loja virtual WooCommerce antes dos ajustes realizados pelo agente de IA.
A loja virtual WooCommerce antes dos ajustes realizados pelo agente de IA.

Pedimos ao Claude que renovasse o design sem alterar o catálogo de produtos ou as funcionalidades de eCommerce existentes.

Primeiro, o Claude analisou as configurações do Astra e do Elementor para identificar as dependências de cores existentes. Em seguida, introduzimos uma nova paleta: bordô (#7B2342), marrom-escuro (#211A16) e marfim (#F7F2EC), além da fonte Cormorant Garamond para os títulos e Jost para o corpo do texto. As alterações também introduziram botões com cantos arredondados e melhoraram o contraste das cores. Por exemplo, o texto branco sobre a cor de destaque principal passou de uma proporção de contraste de 3,98:1 para 9,72:1, superando os requisitos do WCAG AAA para textos de tamanho normal.

O Claude criou um pequeno plugin de uso obrigatório (must-use plugin, ou mu-plugin) no diretório wp-content/mu-plugins/ para carregar CSS personalizado sem modificar os arquivos do Astra ou do WooCommerce.

Os novos estilos introduziram cards de produtos com cantos arredondados, proporções consistentes para as imagens, efeitos sutis ao passar o cursor, etiquetas de categorias mais claras, títulos de produtos com fontes serifadas e preços em bordô. Como o CSS utilizava como alvo a marcação existente da grade de produtos do WooCommerce, as alterações foram aplicadas em toda a loja e em outras listagens de produtos.

A loja virtual WooCommerce após os ajustes realizados pelo agente de IA.
A loja virtual WooCommerce após os ajustes realizados pelo agente de IA.

A primeira tentativa não foi totalmente bem-sucedida. Quando o Claude reformulou o estilo dos botões de pedidos pelo WhatsApp, os botões originais em preto e verde continuaram visíveis ao lado do novo design.

Depois de analisar uma captura de tela, Claude descobriu que o CSS existente do WooCommerce estava substituindo sua regra para ocultar a imagem. Também descobriu que o plugin posicionava o link do WhatsApp entre a imagem do produto e as informações do produto.

O Claude ajustou os seletores CSS e o layout dos cards, movendo o botão para baixo dos detalhes do produto e substituindo o botão grande por outro menor, com bordas totalmente arredondadas.

Aplicando essa abordagem a outros sites WordPress

Nosso experimento se concentrou em uma loja virtual antiga, mas a mesma abordagem pode ser aplicada a outros projetos de manutenção do WordPress.

Para desenvolvedores e agências, a abordagem é simples: auditar a instalação existente, priorizar melhorias específicas, preparar backups, realizar alterações em um ambiente de teste e testar as funcionalidades afetadas antes de prosseguir.

Os prompts também são importantes. Em vez de pedir a um agente de IA que modernize um site inteiro imediatamente, comece solicitando que ele identifique problemas confirmados, examine as dependências e proponha alterações que possam ser testadas individualmente.

Com a Kinsta, os ambientes de teste, o acesso SSH, o gerenciamento de plugins e temas pelo MyKinsta e as ferramentas de backup oferecem uma estrutura prática para esse fluxo de trabalho, sem a necessidade de realizar experimentos diretamente no site em produção.

Joel Olawanle Kinsta

Joel é um desenvolvedor Frontend que trabalha na Kinsta como Editor Técnico. Ele é um professor apaixonado com amor pelo código aberto e já escreveu mais de 200 artigos técnicos, principalmente sobre JavaScript e seus frameworks.