A maior parte do desenvolvimento web não acontece do zero. Isso acontece em bases de código
que acumularam anos de soluções alternativas legadas, polyfills e
utilitários JavaScript (dimensionamento automático, hacks de estilo de caixa de seleção personalizados, listeners
scrollHeight) para coisas que o navegador agora processa de forma nativa. Mas o problema é que
o código antigo não é corrompido. Funciona, então ninguém registra um bug. Também é preciso ter confiança para
refatorar o código de trabalho, mesmo que seja antigo. Por isso, os desenvolvedores ficam compreensivelmente
relutantes.
Por outro lado, não refatorar o código antigo para usar recursos modernos da Web vai custar silenciosamente em tamanho do pacote, capacidade de resposta da página e acessibilidade. Pior ainda, quando você usa agentes de programação nesses projetos, eles copiam as convenções de 2015 do ambiente, além dos padrões desatualizados dos dados de treinamento.
Ao criar algo novo, o Modern Web Guidance direciona seu agente para recursos modernos do Baseline. Para o código atual, o Modern Web Guidance 1.0 adiciona um fluxo de trabalho de modernização que verifica se há padrões legados no projeto e ajuda o agente a fazer upgrade deles.
O que o fluxo de trabalho de modernização faz
Quando você pede ao agente para modernizar um projeto (ou executa o comando legacy-scan
diretamente), veja como ele funciona:
- Verificação local determinista: HTML, CSS, JavaScript/TypeScript,
componentes específicos do framework e arquivos
package.jsonsão verificados rapidamente com analisadores de árvore de sintaxe abstrata (AST), DOM e CSS localmente, sem chamadas de LLM ou custo de token. - Catálogo de regras legadas: um scanner que sinaliza muitos itens em cada execução
é ignorado. Testamos as regras candidatas em aproximadamente 45.000
repositórios de código aberto divididos ao meio: as regras foram escritas e ajustadas na
metade de escrita de regras e avaliadas em uma metade não vista. Descartamos mais regras candidatas do que mantivemos, ignorando recursos que não têm equivalente em código legado e desativando trocas apenas de sintaxe sem retorno real (como reescrever seletores irmãos
+ou~em:has()). Para ser enviada por padrão, uma regra precisa atingir pelo menos 80% de precisão de correspondência estática e 90% de precisão pós-verificação em código não visto. - Filtragem de falsos positivos com base no contexto: cada correspondência de regra vem com
rubricas explícitas de
keepWhen/dropWhen. Isso instrui o agente a avaliar o código ao redor e descartar substitutos intencionais, proteções de CSS@supportsou semelhantes antes de apresentar as descobertas. - Escopo limitado a padrões legados de alta confiança (e em crescimento): o
legacy-scanverifica o subconjunto dos nossos cerca de 200 guias (aproximadamente 20%) em que o código legado pode ser identificado de forma determinística sem falsos positivos, e estamos expandindo essa cobertura ao longo do tempo. Para o restante do catálogo, o agente pesquisa e recupera guias conforme você cria.
Como invocar o fluxo de trabalho de modernização
A modernização de código com o Modern Web Guidance requer a versão 1.0 ou mais recente. Instale ou atualize-o com o npm ou o marketplace de plug-ins do seu agente:
# Install Modern Web Guidance 1.0 in your project
npx modern-web-guidance@latest install
# Or update an existing installation
npx modern-web-guidance@latest update
Como o fluxo de trabalho de modernização faz parte da definição de habilidade principal, é possível acionar o scanner com linguagem natural pedindo ao agente para verificar "padrões legados" ou "modernizar" em um repositório ou pasta.
Observação: se você nomear um único componente, será realizada uma pesquisa de guia normal.
Para demonstrar, veja um exemplo de comando para verificar um repositório inteiro:
Modernize this repository using Modern Web Guidance. Scan our frontend files for legacy patterns, verify the findings, and propose a modernization plan before making any code edits.
Também é possível apontar para uma pasta específica:
Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.
Embora seja possível executar o legacy-scan manualmente no terminal, as integrações automatizadas
de pipeline de CI/CD estão em desenvolvimento.
Exemplos de padrões que ele detecta e corrige
As regras qualificadas visam antipadrões legados comuns em quatro domínios: Formulários e interface, caixas de diálogo e controles, layout CSS, tipografia e design visual e Segurança. Confira abaixo uma tabela de exemplos de padrões legados e as substituições modernas:
Exemplos de transformação de código
Quando solicitado, o agente de programação pode transformar antipadrões legados em modernos com o fluxo de trabalho de modernização. Veja alguns exemplos:
Elementos <textarea> de crescimento automático
O JavaScript legado que mede scrollHeight em cada evento input força o layout
thrashing. Isso pode causar problemas de desempenho, especificamente com a Interaction to Next Paint (INP). Usando o fluxo de trabalho de modernização, seu agente pode corrigir isso:
// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
textarea.style.height = 'auto';
textarea.style.height = `${textarea.scrollHeight}px`;
});
Você não precisa de JavaScript para isso hoje. O fluxo de trabalho de modernização orienta o agente a substituí-lo por CSS:
/* After: Native declarative field sizing */
textarea {
field-sizing: content;
min-block-size: 3lh;
max-block-size: 15lh;
}
Popovers declarativos
A lógica personalizada de modal e pop-up que usa listeners de eventos JavaScript pode ser substituída por atributos HTML padrão:
<!-- Before: a click listener that only calls showPopover() -->
<button id="openBtn">Open Menu</button>
<div id="menu" popover>Menu Content</div>
<script>
openBtn.addEventListener('click', () => menu.showPopover());
</script>
<!-- After: declarative control, no JavaScript -->
<button popovertarget="menu">Open Menu</button>
<div id="menu" popover>Menu Content</div>
Envio seguro de IME
Os listeners de tecla Enter desprotegidos acionam o envio de mensagens prematuramente quando os usuários digitam em editores de método de entrada (IMEs) em japonês, chinês ou coreano.
O agente adiciona proteções de estado de composição:
// Before: Fires mid-composition when confirming kanji/hanzi characters
textarea.addEventListener('keydown', (e) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault();
sendMessage();
}
});
// After: Accurately checks IME composition state
textarea.addEventListener('keydown', (e) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault();
if (e.isComposing || e.keyCode === 229) return;
sendMessage();
}
});
Como funciona: o fluxo de trabalho de modernização em quatro etapas
Refatorar o código de trabalho em um app atual exige confiança, porque ninguém quer
rotatividade automatizada ou regressões sutis. É por isso que não há uma flag --fix: até mesmo as modernizações que parecem simples geralmente se tornam refatorações entre camadas, como excluir um listener JS imperativo ou um pacote npm e mover o comportamento para HTML e CSS, com desafios sutis de comportamento e suporte ao navegador.
Em vez disso, o fluxo de trabalho de modernização executa um loop de quatro etapas com seu agente de programação:
- Verificação (
legacy-scan): o agente executanpx modern-web-guidance legacy-scan <path> --json, que faz uma pré-triagem de arquivos em busca de substrings relevantes, para que ele só ative analisadores de AST, CSS e HTML em arquivos e regras candidatos. Se uma descoberta chegar até aqui, já há uma alta probabilidade (cerca de 92%) de que não seja um falso positivo. Cada correspondência inclui uma lista de verificação para o agente. - Verificação contextual (
keepWhen/dropWhen): como o agente de programação tem o repositório aberto, ele inspeciona o código ao redor de cada correspondência com base na rubrica de verificação dessa regra. Se uma leitura descrollHeightfizer parte da rolagem virtualizada em vez de um hack de<textarea>ou se uma verificação de@supportsjá proteger a propriedade, a descoberta será descartada silenciosamente. - Relatório: o agente resume as descobertas verificadas (observando que
legacy-scanabrange o subconjunto de guias com regras determinísticas, além do plano de modernização, se você pediu para revisar um plano antes de fazer edições). - Recuperação de guias, refatoração e verificação de testes: quando solicitado a
modernizar, o agente executa
npx modern-web-guidance retrieve <guide-id>para buscar o guia apropriado. Ele executa a refatoração do código de acordo com os padrões de compatibilidade do Baseline do guia e executa novamentelegacy-scan <path>nos arquivos modificados, além do pacote de testes do projeto, para confirmar a resolução.
Faça um teste
Seja executando um legacy-scan único no terminal ou pedindo ao agente de programação
para modernizar um módulo mais antigo, o fluxo de trabalho de modernização ajuda você a pagar
a dívida da plataforma da Web legada sem o ruído dos linters tradicionais.
Combine o Modern Web Guidance com o Chrome DevTools para agentes quando quiser passar da modernização de código estático para a verificação, o comparativo de mercado e a depuração em tempo real do navegador.