Planejar a modernização e publicar com reversão

Um site que quebra em produção volta ao ar em segundos com um clique de rollback, não numa madrugada de conserto. A hospedagem guarda cada publicação como um arquivo pronto e promove a versão anterior de volta à principal. Esse clique só existe porque um comando único já barrou o defeito antes do envio, dentro de uma esteira que repete essa checagem sozinha a cada proposta.

O assistente de inteligência artificial que escreve código a partir do seu pedido (o agente) devolve trabalho com falhas previsíveis quando ninguém checa antes de publicar: tipo frouxo, aviso ignorado, nenhum teste. O roteiro que faz esse mesmo agente testar a tela como um usuário fecha o último buraco que a checagem automática não vê.

Encadeie a checagem de tipos, o padrão de código (a revisão automática de estilo, como o corretor ortográfico) e os testes num comando só, chamado verify, e rode-o antes de todo envio. Mire dez segundos: portão lento é portão que alguém pula na sexta-feira apertada, e portão pulado não protege ninguém. Encadeie os passos para que o primeiro que falhar impeça os seguintes.

As ferramentas por trás desse comando mudaram em 2026. O Vite 8 com Rolldown 1.0 é o empacotador de motor único, estável desde março e maio de 2026. Empacotador é a ferramenta que junta os arquivos do site num pacote leve, como embalar o produto antes do envio.

O ganho é de cerca de 25 vezes em 19 mil módulos e de duas a cinco vezes num projeto pequeno. No Next.js 16 o Turbopack é padrão desde 21 de outubro de 2025, com a ressalva da configuração webpack complexa, que pede o Rspack 2.2. No padrão de código, o Biome 2.3+ traz mais de 423 regras e lê tipos sem o compilador completo.

Fora do Tailwind (as classes utilitárias de estilo), o CSS passa pelo Lightning CSS. O Storybook 10, só ESM e 29% menor, é o catálogo onde cada componente (a peça reutilizada, como o botão) é testado sozinho.

Os testes seguem a lógica de portão em degraus. O Vitest roda os testes de unidade em segundos. O Playwright abre o navegador de verdade para o teste de ponta a ponta e compara a foto do SVG compilado entre duas propostas. É o que pega o gráfico que sumiu sem ninguém tocar nele.

Dentro do Playwright, o axe-core é o portão de acessibilidade. Ele cobre de 30% a 40% dos critérios de sucesso e move também o relatório do Lighthouse e o painel do Chrome, o que explica resultados iguais em ferramentas que parecem independentes. O resto é revisão humana, com Pa11y e Lighthouse CI fechando o degrau. O MSW simula o dado que viria da rede, para o teste não depender do servidor.

Rodar a checagem só na sua máquina é frágil: você esquece, ou o que passa no seu notebook falha em outro. O GitHub Actions é a esteira que vem com o repositório e roda os mesmos comandos numa máquina limpa a cada proposta. O arquivo diz a ordem: instalar as dependências travadas, rodar o verify e o build.

Um portão só protege quando bloqueia. Sem a proteção do ramo principal ligada, a checagem só avisa, e aviso ignorado não impede nada de entrar.

Fixe a versão do Chromium que a esteira usa: atualização de motor muda paginação e fonte. Dispare o PDF ou a foto só após um marcador de estado estável, nunca no evento de carregamento: tela que ainda espera dado gera arquivo pela metade.

A chave que autoriza publicar nunca entra no repositório. Se ela já foi enviada num commit, apagar o arquivo não resolve, porque o histórico a preserva; o conserto é trocar a chave no provedor. A esteira concentra credenciais de todos os ambientes: num levantamento de 2026, 59% das máquinas comprometidas eram executores de checagem.

A Vercel (a hospedagem que pega o repositório e publica a cada envio) guarda cada publicação como um arquivo pronto. Promova a anterior de volta à principal e o site volta à versão de ontem em segundos: um susto de cinco minutos em vez de uma madrugada.

O último portão é o agente testando a tela como usuário. A skill webapp-testing (o roteiro que ensina o agente a testar a aplicação local com Playwright em Python) fixa a ordem: reconhecer antes de agir.

O ajudante with_server.py sobe o servidor e roda o script; rode --help antes e trate os scripts como caixa-preta, porque a fonte deles polui a conversa. Para HTML estático, o agente lê o arquivo e acha os seletores (o endereço de cada elemento, por texto, papel, CSS ou id).

Para aplicação dinâmica, ele sobe o servidor, navega e espera a rede sossegar. Só então tira o print ou inspeciona o DOM (a árvore de elementos da página) e escolhe os seletores. Inspecionar o DOM antes de a rede sossegar é a armadilha: o seletor mira o que ainda não existe. Chromium sempre sem janela, navegador fechado no fim.

Um envio com erro de tipo que derruba o cálculo do frete não chega ao site quando o verify bloqueia a entrada na esteira. O roteiro do agente fotografa a caixa vazia no mesmo dia.

Antes de aprovar a próxima publicação, peça o verify encadeado como condição obrigatória na esteira. Trave a versão do Chromium que ela usa e confirme que a chave de publicação mora no cofre da plataforma, nunca no repositório. Rode o roteiro Playwright que testa a tela como o cliente vê e só aprove o envio quando ele passar com a rede sossegada.

Modernizar em cinco ondas, com dois agentes sem se atropelar

Cinco ondas com um portão de verificação entre uma e a próxima modernizam um site antigo sem parar de atender e sem quebrar tudo ao mesmo tempo. A ordem protege o negócio: medição primeiro, depois o caminho do cliente, o visual, o movimento e por último o desempenho, cada onda fechada antes de a seguinte começar.

A pasta separada para cada agente (o assistente de inteligência artificial que escreve código a partir do seu pedido) evita que um apague o trabalho do outro dentro da mesma onda. A onda zero fixa a régua antes de qualquer mudança, e a matriz do manual escolhe a stack de destino pelo cenário do relatório.

Cada onda (uma rodada de trabalho com um único objetivo, fechada por uma checagem antes de a próxima começar) cuida de uma camada só. Atacar as frentes juntas produz, semanas depois, a mesma lista de problemas com coisas quebradas em cima.

A primeira onda só mede: nenhum arquivo muda, e o resultado é um relatório com três números de partida. Entre uma onda e a próxima existe o portão de qualidade (a checagem automática que barra a mudança ruim antes do cliente). Se ele reprova, a onda volta e corrige, e o programa pode parar no meio sem perder o entregue.

Antes da primeira onda existe a onda zero, que fixa a régua com que as outras serão medidas. Ela tem três peças. O orçamento de desempenho é o teto de peso e de tempo de carregamento escrito antes de qualquer tela, como o orçamento da obra antes do primeiro tijolo.

O profiling mede onde o tempo é gasto; o OpenTelemetry é o padrão aberto que registra o que a tela faz em produção, como o odômetro do carro. Produto visual sem esse controle desde a primeira semana degrada em silêncio. Sem a onda zero, a onda cinco chega sem saber se o site ficou mais rápido ou apenas diferente.

Um teto numérico orienta o agente melhor do que "deixe leve". O portão de cada onda compara o número medido com o teto da onda zero.

A stack de destino (o conjunto de ferramentas que constrói e serve a tela) depende do cenário, e a matriz do manual decide numa linha. O board mensal fechado (o relatório da reunião de conselho) pede HTML estático com D3 ou Observable Plot e CSS de impressão.

O investor update pede Astro 7 com MDX e PDF via Playwright. O marketing diário pede React ou Vue com ECharts, Plotly ou ApexCharts 7, ligados às APIs (as portas de dados). O portal recorrente para diretoria pede Next.js 16 ou Astro com camada semântica (a definição de cada métrica em código versionado) e controle de acesso por linha.

O relatório offline seguro cabe num HTML único com DuckDB-Wasm e dados locais; a prova de conformidade pede Typst 0.15. Site que atende dois cenários recebe duas ondas de visual, uma por stack de destino, em vez de uma stack de compromisso que serve mal aos dois.

Dentro de uma onda, dois agentes trabalham juntos desde que cada um tenha a própria pasta e a própria lista de arquivos. O git worktree (um comando do próprio git que cria uma segunda pasta de trabalho ligada ao mesmo repositório) faz a pasta. Cada uma fica no seu ramo e as duas dividem o mesmo histórico, sem duplicar código.

Pasta separada evita a sobrescrita; o escopo disjunto (a lista de arquivos que é só de um agente) evita o conflito na hora de juntar. Se dois agentes citam o mesmo arquivo, o recorte foi mal feito, mesmo com pastas diferentes. Quem precisa de algo fora do próprio escopo relata o que falta, em vez de editar por conta própria.

Escreva o pedido único com a onda zero embutida: descreva o site atual, fixe o teto de tempo e peso e a medição em produção. Peça as cinco ondas na ordem, com o seu aprovado entre uma e a próxima. Para dividir uma onda entre dois agentes, crie uma pasta irmã por ramo com o git worktree, dê a cada uma sua lista de arquivos e incorpore um ramo de cada vez ao final.