vercel-optimize (Optimización de Vercel)

Vercel Optimize (Optimización de Vercel)

Realiza una auditoría de optimización de Vercel basada en observabilidad. No inspecciones archivos fuente hasta que exista signals.json y una puerta determinista apunte a una ruta, archivo o configuración de proyecto.

Doctrina central: lee references/doctrine.md si alguna regla no está clara.

• Métricas primero. Las recomendaciones parten de señales de producción de Vercel, no de búsquedas generales en el repositorio.
• Puertas deterministas. scripts/gate-investigations.mjs decide qué merece ser investigado.
• Ámbito limitado a candidatos. Solo se leen archivos nombrados por un candidato o su cadena de importaciones local a la ruta.
• Citas con versión. Solo se usa references/docs-library.json; las citas inválidas o con versiones incorrectas se eliminan.
• Voz del cliente. Lee references/voice.md antes de redactar informes o mensajes de chat.

Prerrequisitos

• Vercel CLI v53+ con vercel metrics, vercel usage, vercel contract y vercel api.
• Sesión CLI autenticada: vercel login.
• Directorio de aplicación vinculado: vercel link. VERCEL_PROJECT_ID puede ayudar a resolver la configuración del proyecto, pero vercel metrics aún requiere el enlace del directorio. El enlace o el entorno debe incluir el ámbito de organización/equipo/usuario del proyecto previsto para que el recopilador pueda resolver un --scope seguro para CLI y mantener vercel metrics, vercel usage y vercel contract en la misma cuenta.
• Node.js 20+.
• Observability Plus para recomendaciones basadas en métricas a nivel de ruta.

Nunca pongas tokens de autenticación en comandos de shell. No escribas VERCEL_TOKEN=..., --token ... o Authorization: Bearer ... en comandos que puedan aparecer en el chat.

Soporte de Frameworks

El preflight lee package.json y establece expectativas antes del despliegue de métricas.

Framework	Estado	Notas
Next.js App Router	compatible	Mapeo de rutas más robusto, escáneres, guías, citas
Next.js Pages Router	compatible	Limitado a modismos de Pages Router cuando se detecta
SvelteKit	compatible	Mapeo de rutas para archivos src/routes y escáner de SvelteKit
Nuxt	compatible	Mapeo de rutas más comprobaciones genéricas/de plataforma; menos recomendaciones específicas del framework
Astro	limitado	Mapeo de rutas más comprobaciones genéricas; menos recomendaciones específicas del framework
Hono / Remix / desconocido	bloqueado por defecto	Continúa solo si el usuario acepta una auditoría limitada de plataforma/código

Si no es compatible, detente y pregunta antes de escanear o filtrar:

Este proyecto utiliza <framework>. Vercel Optimize admite recomendaciones de código basadas en métricas para Next.js, SvelteKit y Nuxt. El soporte para Astro es limitado. Para <framework>, aún puedo ejecutar una auditoría limitada de plataforma/escáner, pero las métricas de Vercel a nivel de ruta pueden no mapearse a archivos fuente.

¿Quieres que continúe con la auditoría limitada o que me detenga aquí?

Si el usuario continúa, vuelve a ejecutar la recopilación con --continue-unsupported-framework.

Directorio de Ejecución

Usa un directorio de ejecución nuevo para cada auditoría. No reutilices informes, salidas de subagentes ni reportes entre ejecuciones.

RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"

Pipeline

1. Recopilar, escanear y fusionar señales

Ejecuta desde el directorio de la aplicación vinculada o pasa --cwd cuando el script lo soporte. Mantén el stdout JSON separado de los registros de stderr. No combines flujos.

node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"

node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"

Los detalles de recopilación, esquemas, IDs de métricas y comportamiento de degradación están en references/data-collection.md. El registro de métricas está en lib/queries.mjs; mantén todas las consultas en la ventana compartida de 14 días.

collect-signals.mjs resuelve el propietario del proyecto vinculado a commandScope.cliScope y verifica que la cuenta resuelta pueda leer el proyecto resuelto antes de verificar Observability Plus. Los scripts posteriores reutilizan ese ámbito para cada comando de Vercel CLI que acepte --scope. No ejecutes vercel usage, vercel metrics o vercel contract manualmente sin el mismo ámbito; el uso sin ámbito puede reportar la organización personal del usuario mientras que las métricas de ruta provienen del proyecto de equipo.

Si la resolución del proyecto o ámbito es ambigua, detente y pregunta al usuario qué proyecto de Vercel y ámbito de equipo/personal desea auditar. No infieras el ámbito previsto a partir del equipo actual de vercel whoami, y no continúes con la recopilación de métricas, uso o contrato hasta que el enlace, una coincidencia exacta del proyecto en .vercel/repo.json, o VERCEL_PROJECT_ID + VERCEL_ORG_ID identifiquen la cuenta prevista.

Usa este prompt para PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED o PROJECT_SCOPE_MISMATCH:

No puedo identificar de forma segura el proyecto de Vercel y la cuenta para esta auditoría aún.

Por favor, confirma el nombre o ID del proyecto de Vercel y el slug/nombre del equipo, o indícame que está bajo tu cuenta personal. Una vez confirmado, volveré a enlazar o ejecutaré la recopilación contra ese ámbito exacto antes de verificar las métricas.

1.1 Detenerse en bloqueadores

Verifica los bloqueadores antes de filtrar:

jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"

Acciones requeridas:

• frameworkSupportBlocker === "unsupported_framework": usa el prompt de framework no compatible anterior.
• PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED o PROJECT_SCOPE_MISMATCH: detente y pregunta qué proyecto de Vercel y ámbito de equipo/personal desea auditar el usuario. Para proyectos de equipo, vuelve a ejecutar después de vercel link --yes --project <project-name-or-id> --team <team-slug>; para proyectos personales, vuelve a ejecutar después de enlazar bajo la cuenta de usuario prevista o después de establecer tanto VERCEL_PROJECT_ID como VERCEL_ORG_ID.
• observabilityPlusBlocker === null: continúa.
• no_traffic: informa al usuario que las métricas de ruta son escasas; continúa solo si acepta resultados limitados.
• payment_required o no_oplus_probe: muestra references/observability-plus.md textualmente y pregunta.
• project_disabled: informa al usuario que habilite Observability Plus para el proyecto o acepte una auditoría limitada.
• daily_quota_exceeded: detente e informa al usuario que la cuota de consultas de Observability está agotada; reintenta después del reinicio de la medianoche UTC, o pregunta si desea continuar con una auditoría limitada solo de código.
• not_linked: enlaza el directorio de la aplicación, luego vuelve a ejecutar el Paso 1. Si se conocen la ruta de la aplicación y el proyecto:

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# añade --team <team-id-or-slug> cuando se conozca

• forbidden o project_not_found: corrige el ámbito de autenticación/equipo. No promociones Observability Plus.
• all_failed_other: muestra el código de error sin procesar y pregunta si se desea continuar en modo limitado solo de código.

No recurras silenciosamente al modo solo de código. Si el usuario acepta una auditoría limitada, vuelve a ejecutar la recopilación con:

node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"

Luego escanea y fusiona nuevamente.

2. Filtrar candidatos

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"

Forma de la salida:

• toLaunch: candidatos de ámbito de código a investigar.
• platform: recomendaciones de ámbito de proyecto/cuenta.
• gated: candidatos omitidos, cubiertos o descalificados que aún deben aparecer en el informe.
• budget: presupuesto de candidatos y modo de selección.

El presupuesto predeterminado es de 6 candidatos de ámbito de código con un guardarraíl de diversidad. Para expandir:

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"

Documentos de candidatos generados: references/candidates.md.

2.1 Preguntar sobre el alcance de la auditoría cuando sea necesario

Antes del análisis profundo, ejecuta:

node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"

Si shouldAsk es falso, continúa.

Si shouldAsk es verdadero:

1. Imprime exactChatMessage.body exactamente como se devuelve. No resumas, trunques, reordenes ni reescribas.
2. Luego pregunta questionText usando questionPayload cuando el host admita preguntas estructuradas.
3. Si el usuario elige un número diferente, vuelve a ejecutar el filtro con --max-candidates <choice>.

Nunca pongas la vista previa larga dentro del campo de pregunta. La vista previa y la pregunta son superficies separadas.

2.2 Análisis profundo y conciliación

node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <project-dir> > "$RUN_DIR/investigation-evidence.json"

node scripts/reconcile-candidates.mjs "$RUN_DIR/investigation-evidence.json" \
  --gate "$RUN_DIR/gate.json" \
  --out "$RUN_DIR/reconciled-investigation.json"

--cwd debe ser el directorio del proyecto vinculado para que deep-dive.mjs pueda verificar el mismo enlace del proyecto y reutilizar signals.json.commandScope.cliScope para cualquier llamada posterior a vercel metrics.

La conciliación convierte deterministamente los candidatos refutados en observaciones antes de cualquier investigación de fuente:

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 Generar resúmenes e investigar

Lista el trabajo:

node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"

Genera un resumen para cada entrada en briefs-manifest.json.briefs. El group puede ser toLaunch o platform; no generes solo resúmenes toLaunch.

mkdir -p "$RUN_DIR/briefs" "$RUN_DIR/sub-agent-outputs"
node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" \
  --group <brief.group> --index <brief.index> --out "$RUN_DIR/briefs/<brief.group>-<brief.index>.md"

Usa briefs-manifest.json.briefs[].label para nombres de trabajadores visibles, por ejemplo Baja tasa de aciertos de caché en la ruta /docs/llm-digest/[...slug], no toLaunch-7.

Regla de distribución:

• 1-2 resúmenes: investiga en línea.
• 3+ resúmenes: crea un subagente por resumen cuando el host lo admita.
• Hosts sin subagentes: ejecuta en serie en línea.

Contrato del subagente:

• El resumen es el prompt completo.
• Lee solo los archivos listados en el resumen, más las importaciones locales de la ruta cuando sea necesario.
• Emite una recomendación JSON o un hallazgo JSON sin cambios usando references/recommendations.md.
• No cites URLs fuera del subconjunto de citas proporcionado.
• No recomiendes características del framework no disponibles en la versión detectada.

Si un subagente recurre a grep en todo el repositorio, el candidato está mal formado; abandona o abstente en lugar de ampliar el alcance.

2.4 Recopilar salidas

Guarda cada resultado de investigación sin procesar en $RUN_DIR/sub-agent-outputs/, luego recopila:

node scripts/collect-sub-agent-outputs.mjs \
  --manifest "$RUN_DIR/briefs-manifest.json" \
  --out "$RUN_DIR/recommendations.json" \
  "$RUN_DIR/sub-agent-outputs/"

El recopilador extrae JSON, antepone registros pre-resueltos, aplica el orden del manifiesto y falla en valores candidateRef faltantes, duplicados, desconocidos o no coincidentes.

3. Verificar recomendaciones

node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
  --signals "$RUN_DIR/signals.json" \
  --repo-root <project-dir> \
  --out "$RUN_DIR/verify.json"

Este script extrae afirmaciones, verifica archivos/citas/versión, califica la calidad, aplica saneadores, emite verifiedRecommendations, withheldRecommendations, renderableRecommendations, y crea regenPlan para recomendaciones fallidas o inseguras.

Esquema de recomendaciones, reglas de escritura, orden de saneadores y reglas de calificación: references/recommendations.md. Reglas de verificación: references/verification.md.

Para cada entrada de regenPlan, vuelve a ejecutar el mismo resumen con una sección El intento anterior falló estas verificaciones que liste topFailures. Mantén la salida regenerada solo si la verificación mejora sin eliminar citas.

4. Renderizar informe y mensaje final

node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
  --project <name> \
  --out "$RUN_DIR/report.md" \
  --message-out "$RUN_DIR/final-message.json"

Usa --debug-out "$RUN_DIR/debug.json" solo al desarrollar el skill. El Markdown del cliente y la salida del chat no deben exponer passRate, quality, rastros de saneadores, nombres de subagentes sin procesar u otros campos de implementación.

Después de renderizar, imprime final-message.json.body textualmente y detente. No añadas destacados, notas de depuración, recuentos sin procesar, resúmenes de subagentes ni explicaciones adicionales. La deduplicación en tiempo de renderizado, los límites de plataforma y las eliminaciones de seguridad estrictas pueden cambiar el recuento visible para el cliente, así que nunca resumas a partir de verify.json sin procesar.

Estructura del informe y marco de impacto: references/scoring.md.

Reglas de Recomendación

Cada recomendación debe:

• Remontarse a un candidato lanzado, candidato de plataforma, observación pre-resuelta o hallazgo de escáner verificado independiente del tráfico.
• Incluir evidencia métrica observada de signals.json o evidence.deepDive.
• Citar archivos verificados con números de línea cuando esté involucrado código.
• Incluir al menos una cita permitida que se aplique al framework/versión detectado.
• Usar números de rendimiento observados precisos.
• Usar solo frases de magnitud de costo; nunca ahorros de $N visibles para el cliente.
• No recomendar reducciones de duración para endpoints de tiempo de ejecución de Vercel Workflow (/.well-known/workflow/v1/*). Estas son rutas de orquestación generadas para la ejecución de pasos/flujos duraderos y deben estar estrictamente bloqueadas antes de la investigación.
• Las recomendaciones de Workflow deben nombrar el límite que se está cambiando. Ejemplos válidos: encolar trabajo duradero y devolver un ID de ejecución en lugar de esperar a que se complete, corregir reproducción/cierre/bloqueos de flujo, o reducir pasos/segundos de Workflow verificados en exceso.