Tu app hecha con IA ya se despliega en Vercel. El agente añade reglas de rutas a vercel.json, pero al crecer el proyecto es difícil comentar por qué existe cada regla. Vercel anunció el 2 de noviembre de 2026 que todos los proyectos pueden usar vercel.toml: admite las mismas propiedades que vercel.json, pero permite comentarios y una estructura más plana. La utilidad no es cambiar de formato por moda; es hacer que la configuración que la IA edita sea legible y fácil de revisar antes de desplegar.

Cuándo conviene y cuándo no

Si tu proyecto tiene una configuración corta que nadie toca, quizá no ganes nada migrando. La documentación de Vercel destaca TOML para configuraciones grandes, muchas reglas de rewrite o varios servicios en un solo proyecto. Los comentarios sirven para explicar que /api va al backend, que una ruta existe por compatibilidad o que cierto ajuste no se debe borrar. Eso ayuda cuando un agente de código propone un cambio sin conocer el historial.

Hay una regla dura: usa solo uno de estos archivos en la raíz del proyecto: vercel.toml, vercel.json o vercel.ts. No agregues TOML junto al JSON existente esperando que uno sobrescriba al otro. Conserva la versión anterior en Git, haz la migración en una rama y elimina o renombra el archivo viejo dentro del mismo cambio.

Un ejemplo pequeño que sí puedes copiar

Para una app estática cuyo comando de construcción genera la carpeta dist, crea este archivo en la raíz del repositorio. No copies outputDirectory = "dist" a una app Next.js u otro framework sin comprobar su salida: este ejemplo supone una app estática concreta.

"$schema" = "https://openapi.vercel.sh/vercel.json"

# La app estática genera archivos en dist/
buildCommand = "npm run build"
outputDirectory = "dist"
cleanUrls = true

buildCommand ejecuta la construcción, outputDirectory indica dónde quedan los archivos y cleanUrls quita extensiones .html de las URL compatibles. Los nombres de propiedades vienen del ejemplo oficial. El comentario expresa una suposición que debes verificar en package.json; si el build no produce dist, corrige la ruta antes de desplegar.

Valida el formato y la conducta por separado

1. Comprueba la sintaxis. En Python 3.11 o posterior puedes usar tomllib. Si usas una versión anterior, instala tomli y ejecuta python3 -c "import tomli,pathlib; print(tomli.loads(pathlib.Path('vercel.toml').read_text()))". Probé localmente el archivo del ejemplo con tomli y confirmé las tres propiedades. Esto solo prueba que el TOML se puede leer.
2. Compara la configuración vieja. Enumera rutas, redirecciones, headers, cron jobs y variables relacionadas con build antes de migrar. Si el agente omite una entrada, el archivo puede ser válido y aun así cambiar el comportamiento.
3. Despliega a preview. Comprueba la página principal, una ruta interna y cada endpoint importante. Compara respuestas y logs con la versión anterior. Solo entonces incorpora el cambio a producción.

Un prompt que ayuda a revisar la migración

Si delegas el cambio a un agente de código, dale un límite verificable. Puedes copiar este encargo: «Lee mi archivo de configuración actual y el package.json. Propón un único vercel.toml equivalente. Conserva todas las rutas, rewrites, redirects y ajustes de build; añade comentarios solo donde expliquen una decisión. No cambies variables ni secretos. Devuélveme una tabla con cada propiedad anterior, su equivalente y las que no pudiste comprobar. Ejecuta el build local, valida la sintaxis TOML y no hagas un despliegue a producción». Un agente que devuelve una tabla de equivalencias te permite detectar una regla ausente antes de que el archivo nuevo llegue al repositorio principal.

Después de revisar el diff, prueba npm run build en tu máquina y comprueba que dist exista. Si el preview rompe una ruta, revierte el commit de configuración y vuelve a comparar con el JSON anterior; no intentes arreglar a ciegas en producción. Guarda una lista de URL de prueba junto al PR para que la próxima migración se pueda repetir.

Vercel confirma la disponibilidad y equivalencia de propiedades; no desplegué este ejemplo en una cuenta Vercel. La prueba local cubre sintaxis TOML y claves, no compatibilidad real con tu framework. Si tu configuración usa servicios, reescrituras complejas o vercel.ts dinámico, utiliza el ejemplo oficial de Services como punto de partida y valida el preview antes de reemplazar nada.