La mayor parte del desarrollo web no se realiza desde cero. Esto sucede en bases de código existentes que acumularon años de soluciones heredadas, polyfills y utilidades de JavaScript (ajuste de tamaño automático, trucos de diseño de casillas de verificación personalizadas, objetos de escucha de scrollHeight) para cosas que el navegador ahora controla de forma nativa. Pero aquí está el problema:
El código antiguo no se rompe. Funciona, por lo que nadie informa un error. También se necesita confianza para
refactorizar el código de trabajo, incluso si es antiguo, por lo que los desarrolladores se muestran reacios,
lo cual es comprensible.
Por otro lado, no refactorizar el código antiguo para usar funciones web modernas te costará silenciosamente en el tamaño del paquete, la capacidad de respuesta de la página y la accesibilidad. Peor aún, cuando usas agentes de programación en estos proyectos, copian las convenciones de 2015 circundantes junto con los patrones obsoletos de sus datos de entrenamiento.
Cuando creas algo nuevo, Modern Web Guidance dirige a tu agente hacia las funciones modernas de Baseline. Para el código existente, Modern Web Guidance 1.0 agrega un flujo de trabajo de modernización que analiza tu proyecto en busca de patrones heredados y ayuda a tu agente a actualizarlos.
Qué hace el flujo de trabajo de modernización
Cuando le pides al agente que modernice un proyecto (o cuando ejecutas el comando legacy-scan
directamente), esto es lo que sucede:
- Análisis local determinista: Los archivos HTML, CSS, JavaScript/TypeScript,
los componentes específicos del framework y los archivos
package.jsonse analizan rápidamente con analizadores de árbol de sintaxis abstracta (AST), DOM y CSS de forma local, sin llamadas a LLM ni costo de tokens. - Catálogo de reglas heredado: Se ignora un escáner que marca demasiados elementos en cada ejecución. Probamos las reglas candidatas en aproximadamente 45,000
repositorios de código abierto divididos por la mitad: las reglas se escribieron y ajustaron en la
mitad de escritura de reglas y se calificaron en una mitad retenida no vista. Descartamos más reglas candidatas de las que conservamos, omitimos funciones que no tienen un equivalente de código heredado y retiramos los intercambios solo de sintaxis sin un beneficio real (como reescribir selectores hermanos
+o~que funcionan en:has()). Para enviarse de forma predeterminada, una regla debe alcanzar al menos un 80% de precisión de coincidencia estática y un 90% de precisión posterior a la verificación en el código no visto. - Filtrado de falsos positivos adaptado al contexto: Cada coincidencia de regla incluye
rúbricas explícitas de
keepWhen/dropWhen. Esto le indica al agente que evalúe el código circundante y descarte las alternativas intencionales, las protecciones de CSS@supportso las similitudes antes de presentar sus hallazgos. - Se limita a patrones heredados de alta confianza (y en aumento):
legacy-scanverifica el subconjunto de nuestras aproximadamente 200 guías (alrededor del 20%) en las que el código heredado se puede detectar de forma determinista sin falsos positivos, y estamos ampliando esa cobertura con el tiempo. Para el resto del catálogo, tu agente busca y recupera guías a medida que compilas.
Cómo invocar el flujo de trabajo de modernización
Para modernizar el código con Modern Web Guidance, se requiere la versión 1.0 o una posterior. Instálalo o actualízalo con npm o con el mercado de complementos de tu 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 el flujo de trabajo de modernización forma parte de la definición de la habilidad principal, puedes activar el análisis con lenguaje natural pidiéndole al agente que busque "patrones heredados" o que "modernice" un repositorio o una carpeta.
Nota: Si nombras un solo componente, se realizará una búsqueda de guía normal.
Para demostrarlo, a continuación, se muestra un ejemplo de instrucción para analizar un repositorio completo:
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.
También puedes apuntar a una carpeta específica:
Check src/components/forms for legacy web patterns that can be refactored to modern Baseline features.
Si bien actualmente puedes ejecutar legacy-scan de forma manual en tu terminal, las integraciones automatizadas de la canalización de CI/CD están en desarrollo.
Ejemplos de patrones que detecta y corrige
Las reglas calificadas se orientan a antipatrones heredados comunes en cuatro dominios: Formularios y IU, diálogos y controles, diseño de CSS, tipografía y diseño visual, y Seguridad. La siguiente es una tabla de patrones heredados de ejemplo y sus reemplazos modernos:
Ejemplos de transformación de código
Cuando se le solicite, tu agente de programación puede transformar antipatrones heredados en modernos con el flujo de trabajo de modernización. Estos son algunos ejemplos:
Elementos <textarea> de crecimiento automático
El código JavaScript heredado que mide scrollHeight en cada evento input fuerza la destrucción del diseño. Esto puede causar problemas de rendimiento, específicamente con la Interaction to Next Paint (INP). Con el flujo de trabajo de modernización, tu agente puede corregirlo:
// Before: Imperative layout recalculation on every keystroke
textarea.addEventListener('input', () => {
textarea.style.height = 'auto';
textarea.style.height = `${textarea.scrollHeight}px`;
});
No necesitas JavaScript para esto hoy. El flujo de trabajo de modernización guía a tu agente para que lo reemplace por CSS:
/* After: Native declarative field sizing */
textarea {
field-sizing: content;
min-block-size: 3lh;
max-block-size: 15lh;
}
Ventanas emergentes declarativas
La lógica personalizada de modales y ventanas emergentes que usa objetos de escucha de eventos de JavaScript se puede reemplazar por atributos HTML estándar:
<!-- 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>
Envío de entrada seguro para IME
Los objetos de escucha de la tecla Intro no protegidos activan el envío de mensajes de forma prematura cuando los usuarios escriben en editores de métodos de entrada (IME) en japonés, chino o coreano.
Tu agente agrega protecciones de estado de composición:
// 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();
}
});
Cómo funciona: El flujo de trabajo de modernización de cuatro pasos
La refactorización del código de trabajo en una app existente requiere confianza, ya que nadie quiere
una deserción automatizada ni regresiones sutiles. Por eso, tampoco hay una marca --fix: incluso las modernizaciones que parecen sencillas suelen convertirse en refactorizaciones de varias capas, como borrar un objeto de escucha de JS imperativo o un paquete de npm y mover el comportamiento a HTML y CSS, con un comportamiento sutil y desafíos de compatibilidad con navegadores.
En su lugar, el flujo de trabajo de modernización ejecuta un bucle de cuatro pasos con tu agente de programación:
- Análisis (
legacy-scan): El agente ejecutanpx modern-web-guidance legacy-scan <path> --json, que preselecciona archivos para buscar subcadenas relevantes, de modo que solo activa los analizadores de AST, CSS y HTML en los archivos y las reglas candidatos. Si un hallazgo llega hasta este punto, ya existe una alta probabilidad (alrededor del 92%) de que no sea un falso positivo. Cada coincidencia incluye una lista de tareas de verificación para el agente. - Verificación contextual (
keepWhen/dropWhen): Como el agente de programación tiene el repositorio abierto, inspecciona el código que rodea cada coincidencia con la rúbrica de verificación de esa regla. Si una lectura descrollHeightforma parte del desplazamiento virtualizado en lugar de un hackeo de<textarea>, o si una verificación de@supportsya protege la propiedad, el hallazgo se descarta de forma silenciosa. - Informe: El agente resume los hallazgos verificados (ten en cuenta que
legacy-scanabarca el subconjunto de guías con reglas determinísticas, además del plan de modernización si solicitaste revisar un plan antes de realizar ediciones). - Recuperación de guías, refactorización y verificación de pruebas: Cuando se le pide que
modernice, el agente ejecuta
npx modern-web-guidance retrieve <guide-id>para recuperar la guía adecuada. Ejecuta la refactorización del código según los patrones de Baseline compatibility de la guía y vuelve a ejecutarlegacy-scan <path>en los archivos modificados junto con el paquete de pruebas del proyecto para confirmar la resolución.
Probar
Ya sea que ejecutes un legacy-scan único en la terminal o le pidas a tu agente de programación
que modernice un módulo más antiguo, el flujo de trabajo de modernización te ayuda a pagar
la deuda de la plataforma web heredada sin el ruido de los linters tradicionales.
Combina Modern Web Guidance con las Herramientas para desarrolladores de Chrome para agentes cuando quieras pasar de la modernización de código estático a la verificación, la comparativa y la depuración en vivo del navegador.