Modern Web Guidance 1.0: instalação no Claude Code, Codex e Cursor
Instale o Modern Web Guidance 1.0 como skill do projeto no Claude Code, Codex ou Cursor. Verifique a busca e a recuperação de guias, revise os resultados do legacy-scan antes de editar, controle orientações experimentais com .mwgrc e desative a telemetria. Entenda a cobertura limitada do analisador, os custos de contexto e as avaliações do Google.
Conteúdo
Instale o Modern Web Guidance 1.0 como skill do projeto e valide uma tarefa de frontend antes de adotá-lo em todo o repositório. Use legacy-scan para preparar propostas de modernização sujeitas a revisão, não para reescrever código sem supervisão. Defina DISABLE_TELEMETRY=1 antes do primeiro comando quando não quiser enviar telemetria de uso do Modern Web Guidance.
O que muda com o Modern Web Guidance 1.0
O Modern Web Guidance fornece instruções específicas sobre a plataforma web ao seu agente de programação antes que ele escreva código. A versão 1.0, publicada em 10 de novembro de 2026, inclui 203 guias de casos de uso e cobre 250 recursos da plataforma web. As equipes do Chrome, Edge, Firefox e MDN mantêm o projeto junto com a comunidade.
A skill, um conjunto de instruções para o agente, orienta a busca pelos guias relevantes e a recuperação de seu conteúdo. Depois, o agente deve aplicar as regras de implementação e as alternativas de compatibilidade, ou fallbacks.
A busca combina um modelo local de embeddings com BM25, um método de classificação por palavras-chave. Segundo o README oficial do projeto, essa busca não precisa de uma API externa de modelos nem de uma chave de API.
Isso ajuda quando o agente conhece uma API do navegador, mas deixa passar detalhes como o comportamento das transições ou os fallbacks de compatibilidade. Você continua responsável por definir os navegadores compatíveis, revisar as alterações e executar os testes da aplicação.
Como instalar no Claude Code, Codex ou Cursor
Use a mesma instalação pela linha de comando, ou CLI, no escopo do projeto para os três agentes. O código de instalação chama o Vercel Skills. Em 2026-11-13, use Node.js 22.20 ou superior para atender ao requisito atual do instalador Skills. Você também precisa de npm/npx e permissão para baixar os pacotes necessários.
Abra o Bash na raiz do projeto. Desative a telemetria do Modern Web Guidance antes de executar o comando oficial de instalação:
export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest installO instalador interativo permite escolher os agentes de destino. Selecione Claude Code, Codex, Cursor ou apenas os que você usa. Para testar em um repositório específico, mantenha o escopo do projeto, que é o padrão do instalador.
Para essa instalação via CLI, verifique os arquivos do projeto e os métodos de chamada:
| Agente | Arquivo da skill no projeto | Chamada explícita |
|---|---|---|
| Claude Code | .claude/skills/modern-web-guidance/SKILL.md | Digite /modern-web-guidance. |
| Codex | .agents/skills/modern-web-guidance/SKILL.md | Use /skills ou mencione $modern-web-guidance. |
| Cursor | .agents/skills/modern-web-guidance/SKILL.md | Digite / no chat do Agent e selecione a skill. |
Os diretórios correspondem ao mapeamento atual do instalador para cada agente. Não são caminhos de cache de plugins nem de instalação global.
Inicie uma nova sessão do agente no mesmo repositório e chame a skill explicitamente na primeira verificação. Se ela não aparecer, confira o agente selecionado, o escopo da instalação e o local do arquivo antes de reinstalar.
Para atualizar uma skill instalada via CLI, execute no diretório do projeto:
npx modern-web-guidance@latest updateRevise os arquivos da skill que mudaram e repita a verificação de recuperação de guias da próxima seção. Esses comandos usam @latest; não presuma que uma atualização futura continuará na versão 1.0.
A instalação pelo catálogo de plugins é outra opção. Mantenha o processo de atualização dela separado deste procedimento via CLI. Para entender o empacotamento e a gestão de plugins do Claude Code, veja como instalar, verificar e remover plugins do Claude Code.
Verifique a busca, a recuperação e o uso real pelo agente
Verifique tanto a CLI quanto o uso que o agente faz de seus resultados. Um comando bem-sucedido no terminal não demonstra, por si só, que o agente carregou a skill.
Execute no Bash o exemplo documentado de diálogo:
npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"A busca retorna JSON com identificadores e descrições dos guias. A recuperação retorna o conteúdo do guia selecionado. Para saídas grandes, a CLI pode mostrar o caminho de um arquivo salvo em vez do conteúdo. Peça ao agente que leia esse arquivo inteiro.
Depois, chame a skill instalada e dê ao agente uma tarefa de escopo limitado. O prompt abaixo mantém o framework e a política de navegadores e exige a recuperação das orientações antes da edição:
Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.Confira o registro de chamadas de ferramentas para confirmar que houve busca e recuperação. O relatório final deve identificar o guia e explicar quais decisões de implementação vieram dele. A afirmação de que o agente “seguiu boas práticas” não basta como evidência.
O guia de animação de diálogos incluído na versão publicada oferece um ponto concreto para revisão. Quando o código usa a propriedade abreviada transition, transition-behavior: allow-discrete deve vir depois para evitar que seu valor seja redefinido. Teste a entrada e a saída, o comportamento com movimento reduzido e as interações existentes do diálogo.
Se o primeiro comando falhar antes de retornar os resultados, confira primeiro o Node.js e as permissões de download dos pacotes. As instruções da skill publicadas distinguem explicitamente o download do pacote da operação offline. Autorize o comando do pacote necessário, em vez de liberar qualquer execução via npx.
Se os resultados não forem relevantes, tente uma consulta sobre um comportamento concreto, como “confirmation modal dialog”. Não recupere um guia sem relação com a tarefa apenas para fazer o processo parecer bem-sucedido.
Use legacy-scan para revisar, não para reescrever automaticamente
Use legacy-scan para encontrar possíveis modernizações em um repositório ou diretório. Para alterar um componente específico, use a busca e a recuperação de guias. Essa diferença está na documentação do processo de modernização.
Execute uma análise com saída legível a partir da raiz do projeto:
npx modern-web-guidance@latest legacy-scan .Para obter uma saída estruturada que o agente possa revisar, use:
npx modern-web-guidance@latest legacy-scan . --jsonO resultado traz possíveis alterações associadas aos guias relevantes, não arquivos de código-fonte reescritos. O analisador estático não faz chamadas a um modelo de linguagem. As análises e edições posteriores do agente continuam usando seu acesso normal ao modelo.
Peça ao agente que siga as quatro etapas documentadas:
- Analisar o diretório escolhido e reunir os possíveis pontos de alteração.
- Verificar cada resultado com base no código ao redor e nas regras
keepWhen/dropWhen. Descartar falsos positivos em vez de tratar cada ocorrência como uma alteração obrigatória. - Relatar os resultados verificados e as edições propostas. Exigir sua aprovação antes de começar a modernização.
- Aplicar as alterações aprovadas com base nos guias correspondentes, depois de recuperá-los. Executar os testes existentes e analisar novamente o escopo alterado.
Dê atenção especial aos fallbacks intencionais e ao código de compatibilidade condicionado a verificações de suporte. Uma implementação que parece antiga pode continuar necessária para os navegadores que o projeto atende.
O analisador da versão 1.0 cobre aproximadamente 20% dos guias: aqueles com regras determinísticas para detectar padrões antigos. Esse percentual se refere ao catálogo de guias, não ao seu código. Portanto, não encontrar ocorrências não comprova que o projeto esteja totalmente modernizado, acessível ou correto.
Defina a política de navegadores e o .mwgrc antes de modernizar
Deixe os requisitos de compatibilidade explícitos e mantenha as orientações experimentais desativadas, a menos que o projeto precise delas. Por padrão, a skill considera que recursos Baseline Widely available podem ser usados sem fallbacks.
As instruções de configuração do Baseline mostram como registrar o alvo do projeto em AGENTS.md ou CLAUDE.md. Use sua política real de suporte. Não a altere apenas para aceitar uma substituição sugerida.
O arquivo JSON opcional .mwgrc, na raiz do projeto, controla o acesso às orientações experimentais. Para registrar uma política conservadora, incorpore estes campos à configuração existente:
{
"allowOriginTrials": false,
"allowVolatileFeatures": false
}As orientações para recursos voláteis cobrem recursos disponíveis em apenas um motor de navegador. Incluem os lançados nos últimos 3 meses ou que ainda estão em estabilização. Esses guias continuam aparecendo nas buscas, mas recuperá-los exige permissão explícita. As orientações sobre Origin Trial têm uma autorização separada.
Para permitir orientações sobre recursos voláteis, execute este comando no seu próprio terminal interativo do Bash:
npx modern-web-guidance@latest set-allow-volatile-featuresPara orientações sobre Origin Trial, use o comando separado apenas quando necessário:
npx modern-web-guidance@latest set-allow-origin-trialsOs comandos pedem confirmação e definem o valor booleano correspondente como true. Confira o caminho de configuração exibido e a chave alterada. Depois, tente recuperar o guia novamente.
A recusa dentro de um agente ou de um shell não interativo é intencional. A implementação da autorização exige um terminal interativo controlado por uma pessoa. Não peça ao agente para contornar essa verificação.
Essas opções liberam as orientações. Elas não ativam recursos do navegador, não inscrevem seu site em um Origin Trial nem ampliam sua política de navegadores compatíveis.
Controle a telemetria e os custos de contexto
Desative a telemetria no ambiente que realmente inicia o Modern Web Guidance, não apenas em um terminal separado. A seção de privacidade do projeto informa que os dados coletados incluem instalações, nomes de agentes, identificadores dos guias recuperados e consultas geradas pelo agente. Ela também informa que os prompts originais do usuário não são coletados.
As consultas de busca ainda podem revelar detalhes da tarefa. Adicione export DISABLE_TELEMETRY=1 à configuração de inicialização do Bash, como .bashrc, e garanta que o ambiente de comandos do agente herde a variável. Quando necessário, reinicie o agente ou IDE que já estiver aberto com o ambiente atualizado.
No ambiente do Bash usado pelas chamadas de ferramentas, esta verificação confirma o valor sem exibi-lo:
test "${DISABLE_TELEMETRY:-}" = 1O código de saída 0 confirma que a variável vale 1 naquele ambiente. Isso não é uma auditoria do tráfego de rede. A verificação também não determina as configurações de telemetria do provedor do agente nem de outras ferramentas.
A busca offline também não significa que todo o processo funcione sem rede. O download dos pacotes exige acesso à rede. A telemetria do Modern Web Guidance fica ativa enquanto não for desativada.
Para planejar o uso de contexto, o README anuncia aproximadamente 205 tokens para modern-web-guidance e 175 tokens para chrome-extensions. Esses números não são um limite para uma tarefa completa do agente. Os guias recuperados acrescentam conteúdo à janela de contexto, enquanto a verificação e as edições exigem mais trabalho do agente.
Meça o uso real em tarefas representativas. Não calcule a economia apenas pelo tamanho anunciado da skill.
Use os ganhos da avaliação como motivo para fazer seu próprio teste
Os resultados do Google justificam testar a skill, mas não garantem uma taxa de sucesso universal nem economia de tokens. O registro de resultados do README oficial, de 2026-11-08, apresenta:
| Agente e identificação do modelo | Tarefas / asserções | Sem guias | Com guias | Ganho |
|---|---|---|---|---|
claude_code / opus-5-5 | 215 / 1801 | 57% | 88% | 31 pontos percentuais |
codex_cli / gpt-6.1-sol | 215 / 1795 | 54% | 82% | 28 pontos percentuais |
antigravity_cli / gemini-4-argon | 214 / 1673 | 58% | 94% | 36 pontos percentuais |
São taxas de aprovação em asserções, não percentuais de projetos de produção concluídos com sucesso. As quantidades de tarefas e asserções também variam entre as linhas. Não trate a tabela como um ranking controlado de modelos submetidos à mesma carga de trabalho.
A metodologia do painel de avaliação define a taxa de aprovação como verificações aprovadas divididas por verificações executadas. Execuções que falham ou excedem o tempo limite antes da avaliação são excluídas junto com a execução pareada.
O Google desenvolveu a avaliação com base nos próprios guias. Sua explicação dos erros comuns dos agentes descreve a comparação dos resultados com as expectativas definidas por cada guia. Trate esses números como resultados do fornecedor da ferramenta, não como validação independente da qualidade da sua aplicação.
Antes de adotar a skill, compare uma tarefa representativa em um componente com e sem as orientações. Mantenha o mesmo modelo, prompt e política de navegadores. Revise o comportamento relevante no navegador, os testes de regressão, o tempo investido e o uso real.
Para avaliar os gastos, considere o custo por tarefa de programação concluída, não apenas o preço dos tokens. Mantenha o Modern Web Guidance quando ele melhorar as verificações importantes do repositório sem acrescentar custos inaceitáveis de revisão ou uso.
