Tu agente dice que el deploy falló por vercel.json y propone cambiar la configuración. Pero quizá el CLI apunta al equipo equivocado, el proyecto no está vinculado o Vercel tiene una incidencia. Adivinar y editar archivos en producción suele empeorar el diagnóstico. Desde el 3 de noviembre de 2026, Vercel CLI incluye vercel doctor para separar esos casos antes de hacer cambios.

El anuncio oficial de Vercel indica que el comando revisa la versión e instalación del CLI, el inicio de sesión y equipo actual, la vinculación del proyecto, vercel.json y las incidencias activas de la página de estado. Cada check queda como OK, Warning, Failed o Skipped. Si vercel upgrade no logra actualizar el CLI, muestra de dónde se ejecuta y cómo reinstalarlo.

La prueba que haría antes de un deploy

Actualiza a una versión reciente de Vercel CLI y, desde el directorio del proyecto, ejecuta:

vercel doctor

Si el diagnóstico lo leerá un agente o una automatización, usa vercel doctor --json. La salida estructurada incluye el estado de cada check y comandos sugeridos para corregirlo. Evita pedirle al agente que haga vercel login, vercel link o cambios de configuración antes de leer el resultado. Según Vercel, Doctor no abre prompts, no inicia sesión y no vincula proyectos; incluso funciona sin login o sin proyecto vinculado. Eso lo hace adecuado como primer paso de observación.

Cómo interpretar un resultado sin automatizar errores

1. Si el equipo actual es incorrecto, revisa el contexto de cuenta antes de modificar vercel.json. Un error de permisos no se arregla cambiando rutas.
2. Si el proyecto aparece sin vínculo, decide si este repositorio debe vincularse; no aceptes que un agente elija un proyecto por similitud de nombre.
3. Si vercel.json falla, compara la ruta y el valor señalado con la configuración versionada. Cambia una cosa, vuelve a correr Doctor y luego prueba el deploy.
4. Si hay una incidencia activa, consulta la página de estado y espera o prepara un plan alterno. Reintentar deploys iguales puede ocultar la causa.
5. Para Skipped, identifica qué prerrequisito faltó: no lo cuentes como prueba superada.

Un ejemplo para vibe coding: Claude Code genera una app y al publicar recibe un error. El prompt seguro sería: «Ejecuta vercel doctor --json, resume checks fallidos con evidencia y propón un cambio mínimo; no edites configuración ni vincules otro proyecto hasta que yo confirme el diagnóstico». Aquí la herramienta aporta datos; la elección de cuenta, proyecto o cambio sigue siendo tuya. En un equipo, guarda la salida del diagnóstico sin compartir tokens o información sensible de la terminal.

Qué no demuestra

Doctor comprueba preparación del CLI y del proyecto, no que tu aplicación compile, que los tests pasen ni que el tráfico funcione tras el deploy. Un estado OK tampoco certifica seguridad. Usa los logs del build y una prueba de la URL desplegada para completar el diagnóstico. SoyJB no ejecutó Doctor en una cuenta Vercel propia durante esta nota; el flujo es una prueba propuesta basada en el anuncio oficial. La decisión práctica es simple: antes de dejar que un agente “arregle Vercel”, dale un resultado de diagnóstico y exige que lo explique.