El documento AGENTS.md de Vercel enseña a los asistentes de IA las 70 mejores prácticas de React.
Una visión práctica de la habilidad react-best-practices de Vercel, que muestra cómo integra 70 reglas de React probadas en entornos reales directamente en el código generado por IA.
Un colega del equipo de la plataforma compartió un enlace en un canal interno de Slack sin ninguna explicación: solo la URL directa y un emoji de encogimiento de hombros. El enlace apuntaba al repositorio vercel-labs/agent-skills, específicamente a la habilidad react-best-practices. La expectativa inicial era que se tratara de otro artículo tipo “consejos de rendimiento para React” actualizado para la era de la IA. Pero no fue así. En realidad, se trata de un manual con 70 reglas distribuidas en 8 categorías, que Vercel describe como fruto de más de una década observando cómo las aplicaciones React y Next.js en producción fallan de manera recurrente. Lo importante es que está diseñado para ser utilizado primero por un asistente de programación basado en IA, y solo secundariamente por desarrolladores humanos.
Ese enfoque es realmente el núcleo de lo que hace que esto sea notable, y merece una pausa antes de adentrarnos en el contenido real de las reglas.
Qué hay realmente en el repositorio
Instalar la habilidad requiere un único comando:
npx skills add vercel-labs/agent-skills
Detrás de escena, esto se compila en un archivo AGENTS.md: una convención que cobra popularidad como forma de proporcionar contexto estructurado del proyecto a los agentes de programación (herramientas como Claude Code, Cursor, Codex y OpenCode buscan este archivo). Una vez que está en su lugar, tu agente dispone de un manual de reglas al que puede recurrir al escribir o revisar código, en lugar de depender únicamente de los diversos tutoriales de React que casualmente se hayan incluido en sus datos de entrenamiento.
Las 70 reglas están divididas en ocho categorías, cada una con una etiqueta de prioridad que va desde CRÍTICO hasta BAJO. Las dos categorías marcadas como CRÍTICO son, como era de esperar, las que el equipo de Vercel señala como las principales fuentes de problemas en entornos reales: operaciones asíncronas secuenciales que generan efecto en cascada y un aumento no controlado del tamaño de los paquetes. Una regla típica de la categoría de efecto en cascada expresa esta idea de la siguiente manera:
// Flagged: sequential awaits create a waterfall
async function getThreadPage(threadId) {
const thread = await getThread(threadId)
const author = await getAuthor(thread.authorId)
const replies = await getReplies(threadId)
return { thread, author, replies }
}
// Preferred: parallelize independent fetches
async function getThreadPage(threadId) {
const [thread, replies] = await Promise.all([
getThread(threadId),
getReplies(threadId),
])
const author = await getAuthor(thread.authorId)
return { thread, author, replies }
}
Nada de esto es revolucionario si has pasado tiempo desarrollando con React. Lo realmente interesante no es el contenido de la regla, sino que ahora existe en una forma que las máquinas pueden analizar y aplicar de manera uniforme en todo el código, incluso a las 2 a.m., en una solicitud de integración que nadie examinó detenidamente, sin la fatiga ni los atajos que surgen cuando se acerca una fecha límite.
Por qué esto es diferente de un linter
La reacción inmediata es preguntarse si se trata simplemente de ESLint con otra apariencia. En cierto sentido, sí; pero es el mecanismo lo que lo diferencia. Un linter señala un problema después de que el código ya existe. Este enfoque tiene como objetivo influir en el código mientras aún se está generando, detectando el problema antes incluso de que se escriba. Si un asistente de IA es responsable entre el 30 y el 60 por ciento de las diferencias en una solicitud de integración determinada (y las estimaciones sobre esta cifra varían mucho según a quién se le pregunte en el equipo), integrar las reglas directamente en el proceso de generación representa un tipo de influencia fundamentalmente diferente a la de detectar errores después de que estos hayan ocurrido.
También existe un tipo de orientación para la que los herramientas de análisis de código simplemente no son adecuadas: las decisiones de carácter arquitectónico. Una regla como “evitar crear un modelo en cascada” es, al menos de forma aproximada, algo que una herramienta de este tipo podría aplicar con suficiente configuración personalizada y tolerancia a los falsos positivos. Pero algo como “este componente probablemente debería convertirse en un Componente Servidor, ya que no tiene comportamiento interactivo y los límites del cliente definidos alrededor de él parecen arbitrarios” requiere un razonamiento real sobre la intención y la estructura; precisamente el tipo de decisión para la que se querría que interviniera un agente, en lugar de algo impuesto mediante coincidencias de patrones.
Dónde aparece el escepticismo
Vale la pena mencionar directamente la parte problemática. Un conjunto de reglas elaborado por la misma empresa que desarrolla el framework, y cuya plataforma de hosting recompensa casualmente ciertos patrones de rendimiento, no es por defecto un documento neutral. Algunas de las directrices de nivel CRITICAL relacionadas con el tamaño del paquete coinciden de manera un poco demasiado perfecta con los patrones que también hacen que los propios paneles de análisis y la configuración de caché en el edge de Vercel se vean excelentes. Esa superposición no significa automáticamente que los consejos sean malos. Evitar las estructuras asincrónicas es una buena práctica de ingeniería, sin importar quién sirva su aplicación. Aun así, es lógico tener en cuenta que las “mejores prácticas” seleccionadas por el proveedor nunca son meros elementos técnicos: siempre hay un ligero matiz de marketing incorporado junto con los consejos técnicos.
La segunda preocupación es más estructural: ¿qué sucede cuando 70 reglas se convierten en 200, o cuando las habilidades de proveedores competidores comienzan a aparecer en el mismo archivo AGENTS.md y se contradicen entre sí? Por ahora, con un único repositorio y un concepto completamente nuevo, todo parece ordenado y fácil de comprender. Sin embargo, si avanzamos dieciocho meses, es fácil imaginar que cada framework, cada proveedor de hosting y cada sistema de diseño querrá tener sus propias habilidades instaladas. En ese punto, su agente podría verse obligado a lidiar con un montón de libros de reglas que ofrecen orientaciones contradictorias, y podría no haber una forma obvia de determinar cuál de ellas debe prevalecer.
Probándolo con un código real
Más por curiosidad que por expectativa, se probó esta herramienta en un panel interno de tamaño medio para ver qué resultados daría realmente. Los hallazgos de tipo CRITICAL y HIGH resultaron ser bastante cotidianos: un puñado de llamadas secuenciales await que podrían haberse ejecutado en paralelo, un par de componentes del cliente que no tenían razón real para serlo, y un caso ligeramente vergonzoso de utilizar toda una biblioteca para manejar fechas solo con el fin de formatear un único valor. Nada de esto sorprendería a quien ya haya realizado un análisis serio del rendimiento en una base de código React. Lo que sí llamó la atención fue la velocidad: el agente necesitó aproximadamente cuatro minutos para localizar y marcar todo ello, en comparación con el tiempo que tardaría un revisor humano en detectar los mismos problemas dispersos en una gran solicitud de integración.
Esa diferencia de velocidad es realmente la principal ventaja aquí. Las reglas en sí no son revolucionarias: la mayoría de los ingenieros experimentados ya poseen este conocimiento de forma instintiva. Lo que cambia es que ahora las reglas se aplican con una consistencia y velocidad que un revisor humano, especialmente uno que ya está en su tercera revisión del día, simplemente no puede mantener.
Un beneficio subestimado: enseñar, no solo hacer cumplir
Lo que realmente cambió el cálculo no fueron las propias verificaciones de rendimiento, sino observar cómo un nuevo miembro del equipo utilizaba la herramienta. Esta persona llevaba solo unos meses en el equipo y aún estaba familiarizándose con la base de código. Antes de abrir una solicitud de integración, pidió a su agente que la revisara primero. El agente detectó un patrón de tipo “cascada” y, en lugar de simplemente marcarlo, explicó en lenguaje sencillo —vinculándolo directamente a la regla específica— por qué ejecutar esas llamadas en paralelo era importante en ese contexto concreto. Esa experiencia fue significativamente diferente a la que se tiene con un analizador de código que solo muestra un ID de regla y un mensaje breve al que luego hay que buscar por separado. Se sentía más como si un ingeniero senior dejara un comentario de revisión realmente útil, excepto que los comentarios llegaban incluso antes de que la solicitud saliera del estado de borrador.
Ese podría ser el caso de uso más convincente aquí, más que “la IA escribe código más limpio”. Está más cerca de “la IA enseña mejores hábitos”, de forma continua y sin necesidad de que alguien dedique tiempo a la tutoría o escriba documentación de incorporación que se vuelve obsoleta en seis meses. Si este beneficio persistirá una vez que un equipo tenga instalados cincuenta archivos de habilidades superpuestos, cada uno con sus propias opiniones y algunas inevitablemente en conflicto con otras, sigue siendo una pregunta abierta. Pero para un equipo pequeño formado por un ingeniero experimentado y unas pocas personas que aún están aprendiendo, ya parece ser un verdadero multiplicador de efectos.
Dónde deja esto a las cosas
Dicha habilidad terminó instalándose en la configuración compartida del equipo, sobre todo porque las desventajas son mínimas y las ventajas —un agente que deja de escribir código en formato cascada— constituyen un intercambio razonable. Aún no está claro si este patrón se convertirá en la forma predeterminada en que los frameworks transmiten sus instrucciones a los agentes de IA, o simplemente se convertirá en otro archivo de configuración que se va deteriorando silenciosamente una vez que pase la novedad y nadie se moleste en actualizarlo. Es una pregunta que vale la pena revisar en seis meses en lugar de responderla ahora.
Lecturas relacionadas
- Dentro de la reescritura en Go de TypeScript 7: Mayor velocidad sin cambios en el código — Aprenda cómo el compilador basado en Go de TypeScript 7 permite compilaciones 8-12 veces más rápidas, por qué funciona este cambio de arquitectura y cómo actualizar de forma segura los proyectos existentes.