Implementar Sitio
Desplegar el sitio de marketing Next.js (web/site/) en producción de Vercel, pero tratarlo como un objetivo, no como un comando único: implementar cada corrección relacionada con el sitio en main, desplegarlo, demostrar que funciona en producción en todas las páginas y el flujo de captura de correo electrónico en escritorio y móvil, y seguir corrigiendo + redistribuyendo hasta que todo esté verde.
Contrato del objetivo
Ejecuta esta habilidad como un bucle cerrado. No declares éxito solo con un despliegue limpio de Vercel; un despliegue puede tener éxito mientras una página da error 500, un diseño se rompe en móvil o la escritura de la lista de espera falla en silencio.
- HECHO cuando: todas las correcciones relacionadas con el sitio están confirmadas y enviadas a
main, el despliegue de producción tuvo éxito, cada ruta a continuación devuelve 200 y se renderiza correctamente en escritorio y móvil sin errores de consola/red, y el flujo de captura de correo electrónico acepta un envío y lo persiste (demostrado por lectura de administrador), sin dejar filas de prueba. - NO HECHO (repetir bucle) cuando: cualquier ruta no se renderiza, un diseño se rompe en un viewport, la consola muestra errores o la captura de correo no hace un round-trip completp. Corregir en el código fuente, reimplementar, redistribuir, reverificar.
- BLOQUEADO (detener e informar) cuando: una corrección necesita una credencial/decisión que no tienes (por ejemplo, almacén KV caído, token de administrador faltante, autenticación de Vercel caducada), o el mismo fallo sobrevive a 3 intentos de corrección. Informa el fallo exacto + lo que intentaste; no bucles para siempre.
Mantén un registro breve de cada iteración (qué falló, qué cambiaste, resultado de la reverificación) para que el bucle sea auditable. Si el usuario quiere esto como un /goal persistente, apunta el objetivo a esta habilidad y usa las mismas condiciones HECHO/BLOQUEADO.
El bucle
Fase 0 Alcance e implementar recopilar correcciones del sitio -> verificar localmente -> confirmar -> enviar a main
Fase 1 Desplegar compilar -> npx vercel@latest --prod (desde la raíz del repositorio)
Fase 2 Verificar (producción) Flujo de trabajo: rutas x viewports + captura de correo
Fase 3 Clasificar ¿algún rojo? corregir en el código fuente -> volver a la Fase 0
¿todo verde? -> HECHO
Contexto
- Proyecto:
opentracesen Vercel (ámbitojayfareis-projects) - Framework: Next.js 16 (App Router)
- Directorio raíz: Vercel está configurado con la raíz en
web/site/ - Dominio: opentraces.ai (producción: https://opentraces.ai)
- Compilación:
next build(se ejecuta desdeweb/site/) - Versión: Lectura automática desde
src/opentraces/__init__.pyen tiempo de compilación a través denext.config.ts - Captura de correo electrónico:
EarlyAccessFormenvía a/api/waitlist(Upstash/KV en prod). Se renderiza en/(a través deHubTeaser) y/hub. Consulta la sección de Referencia para selectores + lectura de administrador.
Fase 0 — Alcance e implementar las correcciones del sitio
-
Encuentra lo que está relacionado con el sitio y no implementado. El árbol de trabajo a menudo contiene una mezcla de cambios del sitio y de otros. Implementa solo las correcciones del sitio aquí (el resto es un asunto separado).
git status --short web/site/ git status --short -- ':!web/site/' # cambios que no son del sitio, normalmente déjalos git log --oneline origin/main..HEAD -- web/site/ # confirmaciones del sitio aún no enviadas -
Verificación local antes de implementar (puerta). Ejecuta el sitio contra el servidor de desarrollo ya en ejecución y verifica la superficie modificada con agente-navegador: claro + oscuro, escritorio + móvil, la interacción específica que cambiaste, además de consola/red limpia. Esta es la puerta previa a la implementación; no confirmes una regresión visual. (Si no hay un servidor de desarrollo activo,
cd web/site && npm run deven un puerto libre, verifica, luego detenlo.) -
Compilar localmente (detecta errores de tipo/compilación que el servidor de desarrollo oculta):
cd web/site && npm run buildCorrige cualquier fallo de compilación antes de continuar.
-
Confirmar en main y enviar. Según la convención del proyecto, confirma directamente en
main(no crees automáticamente una rama de funcionalidad a menos que se solicite). Mantén la confirmación limitada a la corrección del sitio; coautoría la confirmación según la regla de pie de página del repositorio.git add web/site/ # prepara solo las correcciones del sitio que verificaste git commit -m "fix(site): <lo que cambió>" git push origin main
Fase 1 — Compilar y desplegar
Despliega desde la raíz del repositorio (no web/site/), porque Vercel resuelve el directorio raíz desde su configuración del proyecto (rootDirectory=web/site). Ejecutar desde dentro de web/site/ duplica la ruta. Siempre fija la CLI más reciente (npx vercel@latest).
cd /ruta/a/la/raíz/del/repo
rm -rf web/site/.next kb/app/.next # salida de compilación obsoleta; infla la subida
npx vercel@latest --prod --yes
NO uses --archive=tgz (medido el 2026-06-26, CLI 54.x). --archive=tgz comprime todo el árbol de trabajo y omite .vercelignore, por lo que arrastra .git-sin-nada-más más kb/, .otbox/, web/site/.next-test/, etc. — una subida de ~3 GB / 1998 archivos que tarda minutos y una vez se colgó durante ~20 min en "Extrayendo archivos de despliegue" en la máquina de compilación (una parada real de producción que tuvimos). La ruta predeterminada archivo por archivo en vercel@latest en cambio:
- respeta
.vercelignore→ ~628 archivos / ~40 MB, - se sube en ~2 s y alcanza el estado LISTO en ~60 s de extremo a extremo,
- no alcanza el
Error: Subida abortadaque--archive=tgzse agregó originalmente para esquivar (eso fue un error de punto final de brew 41.x;vercel@latestlo corrigió, por lo que la solución alternativa ahora es negativa neta).
Si una CLI futura regresa la ruta archivo por archivo y debes recurrir a --archive=tgz, espera el archivo de ~3 GB y una extracción de varios minutos (ocasionalmente estancada); reintenta el despliegue si se cuelga en la extracción.
Captura la URL/ID del despliegue de la salida; lo referenciarás en el informe de verificación.
Consejo: puedes verificar primero un despliegue de previsualización de Vercel (omite
--prod) y ejecutar la Fase 2 contra la URL de previsualización antes de promocionar. Esto mantiene las pruebas de captura de correo electrónico completamente fuera de la lista de producción.
Fase 2 — Verificar en producción (arnés JIT a través de Workflow / ultracode)
Demuestra que el sitio en vivo funciona. Esta fase es un arnés justo a tiempo: tú (el planificador) delimitas el alcance de la ejecución para este despliegue, la herramienta Workflow (el tiempo de ejecución determinista) lo ejecuta, y los workers del navegador efímeros devuelven cada uno contra un esquema tipado. El estado intermedio reside en las variables del arnés, no en tu contexto, por lo que la matriz completa se ejecuta sin llenar tu ventana. Esta habilidad opta explícitamente por la orquestación de Workflow (ultracode).
El arnés está empaquetado y congelado junto a esta habilidad:
verify-site-deploy.workflow.js. No pegues el script en línea; ejecuta el archivo.
Qué verificar
- Rutas (cada una debe devolver 200 + renderizar, sin errores de consola/red):
/,/explorer,/hub,/schema,/docs, más una verificación puntual de páginas profundas:/schema/0.6.0,/docs/getting-started/installation,/docs/cli/commands,/docs/schema/trace-record. - Viewports: escritorio
1440x900y móvil390x844(clase iPhone). Donde una corrección tocó el tema, también verifica claro + oscuro. - Por página: HTTP 200, contenido principal visible, sin desbordamiento/recorte de diseño en el viewport, consola limpia, sin solicitudes de red fallidas, navegación funciona.
- Captura de correo electrónico (su propio agente, ver más abajo).
Verificación de captura de correo electrónico (no contaminar la lista de producción)
/api/waitlist escribe en un almacén en vivo y no tiene un endpoint DELETE, así que sé deliberado:
- Round-trip real (una vez, escritorio): envía una dirección etiquetada como
deploy-verify-<marca de tiempo>@opentraces.ai. Espera HTTP 200{ok:true}y que el botón cambie al estado de éxito. Confirma que se persistió con la lectura de administrador (GET /api/waitlist+Authorization: Bearer $WAITLIST_ADMIN_TOKEN), anotando el recuento antes/después. Luego límpialo eliminando esa fila del almacén (UpstashZREM), y vuelve a leer para confirmar que el recuento ha vuelto. Deja la lista prístina. - Ruta de deduplicación: envía la misma dirección dos veces, espera "ya estás en la lista" con el recuento sin cambios.
- Verificaciones de UI móvil + repetidas sin escribir: llena el honeypot oculto (
input[name=company]) al enviar. El endpoint devuelve un falso-éxito silencioso y nunca almacena la fila, por lo que puedes confirmar la UI de éxito en móvil sin agregar basura. (Si ves "éxito" pero el recuento no se movió, eso es el honeypot funcionando, no un error.) - Si el endpoint devuelve 503 ("la lista de espera no está configurada"), el almacén KV no está conectado en ese despliegue: eso es BLOQUEADO (problema de entorno/almacén), no una corrección de código. Repórtalo.
Ejecutar el arnés
Invoca el artefacto empaquetado con la herramienta Workflow. Delimita su alcance por despliegue con args (este es el paso "planificador" JIT):
Workflow({
scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
args: {
baseUrl: "https://www.opentraces.ai", // host canónico; o una URL de previsualización para mantener el correo fuera de producción
changed: ["/hub", "/"], // rutas que tocó este despliegue -> verificación profunda; el resto se prueba superficialmente
pagesOnly: false // true = omitir la escritura de correo (la validación de solo lectura se ejecuta)
}
})
Devuelve { base, scoped, failures, allGreen }. allGreen: true significa que la Fase 2 pasó; de lo contrario, failures enumera exactamente qué corregir en la Fase 3.
Cómo aplica el arnés las primitivas JIT (consulta
kb/docs/concept-jit-harnesses-generic.md):
- Clasificar y enrutar: si pasas
changed, esas rutas obtienen una verificación completa del navegador (consola, desbordamiento, captura de pantalla); cada otra ruta es solo uncurleconómico para el estado. Flujo de control JS simple que posee el tiempo de ejecución, ningún modelo en la costura, por lo que un despliegue delimitado sigue siendo económico. - Un worker de barrido determinista por viewport (2 workers, no ~18): cada uno ejecuta un solo lote bash fijo (
curl+ un conjunto limitado de llamadas de agente-navegador por ruta) en un modelo económico (haiku) y devuelve el JSON analizado. Sin un prompt abierto de "verifica todo", por lo que el modelo no puede hacer bucles; cada lote abre una sesión del navegador y la cierra conclose --all, por lo que los procesos de Chrome no se acumulan. (Validado el 2026-06-09: ~16s para un barrido completo de viewport profundo, 1 proceso sobrante, frente a las 54 procesos / 15+ min del diseño original por celda.) - Confirmación adversaria independiente: cualquier ruta que un barrido marque como fallida es re-verificada por un worker separado con una sesión limpia (modelo predeterminado) que intenta reproducirla; un fallo sobrevive solo si la confirmación también falla, por lo que un error del agente-navegador no se disfraza de un error del sitio.
- Contratos tipados: cada worker devuelve contra
PAGE_VERDICT/EMAIL_VERDICT, por lo que los resultados se fusionan mecánicamente. - Captura de correo electrónico tiene su propio worker que demuestra la escritura a través de una lectura de administrador independiente y limpia la fila de prueba (consulta las reglas de no contaminación anteriores).
Para cambiar la matriz, la política de profundidad o el esquema de veredicto, edita el archivo .js, es la fuente única de verdad. Si un cambio es de una página y no deseas orquestación, aún puedes ejecutar la verificación de esa página secuencialmente con la habilidad de agente-navegador en la sesión principal.
Fase 3 — Clasificar e iterar
Lee los failures del flujo de trabajo:
- Vacío -> el objetivo se ha cumplido. Informa: ID/URL del despliegue, rutas verificadas, viewports, round-trip de correo electrónico demostrado + limpiado. HECHO.
- No vacío -> para cada fallo, encuentra la causa raíz en el código fuente de
web/site/, corrígelo y vuelve a la Fase 0 (verificar localmente -> confirmar -> enviar -> desplegar -> reverificar). Vuelve a ejecutar la verificación limitada primero a las rutas fallidas, luego una pasada completa una vez que estén en verde. - Después de 3 intentos fallidos en el mismo fallo, o ante un bloqueo de credenciales/almacén/autenticación, detente e informa como BLOQUEADO con el error exacto y lo que intentaste.
Registra cada iteración en el registro en ejecución para que el bucle sea auditable.
.vercelignore
La ubicación importa: el archivo efectivo es .vercelignore de la raíz del repositorio. Incluso si el Directorio Raíz del proyecto es web/site, se sube todo el repositorio (la compilación lee ../../src/opentraces/__init__.py y ../../skill/SKILL.md), y el único .vercelignore que la subida archivo por archivo respeta es el que está en la raíz del repositorio — los patrones se comparan de forma relativa a la raíz del repositorio. Un web/site/.vercelignore es ignorado; no agregues uno (verificado el 2026-06-26 a través de npx vercel@latest --debug).
Es una lista de ignorados positivos (directorios enumerados explícitamente, no un comodín * con negaciones ! — las negaciones son frágiles y se rompen entre versiones de CLI). Sin ella, la subida incluye los árboles pesados del repositorio. Los grandes que debe excluir (cada uno fue una filtración real que corregimos):
kb/(~2.4 G),.claude/(~1.5 G),tests/(~1.4 G),.venv*/(~0.8 G).otbox/(~613 M de tarballs de instantáneas)web/site/.next-test/(~98 M / más de 1000 archivos — ten en cuenta que**/.next/no coincide con el sufijo-test, por lo que.next-test/necesita su propia regla)web/viewer/,web/coming-soon/,web/metrics-worker/
Advertencia:
.vercelignoresolo filtra la ruta de subida archivo por archivo. La bandera--archive=tgzlo omite (consulta la Fase 1 — otra razón para no usarla).
Para verificar qué se subiría después de editar .vercelignore, ejecuta npx vercel@latest --debug desde la raíz del repositorio y lee la línea Encontrados N archivos … M requeridos para subir, luego Ctrl-C — no es necesario un despliegue completo. Un despliegue saludable del sitio es ~628 archivos, no ~2000.
Archivos que NO deben ser ignorados (la compilación los lee en tiempo de compilación):
| Archivo | Leído por | Propósito |
|---|---|---|
src/opentraces/__init__.py | next.config.ts | Detección de versión para version.json |
skill/SKILL.md | lib/docs.ts (getSkillContent()) | Contenido de vista de máquina en páginas de documentación |
Si agregas un nuevo archivo que el sitio lee en tiempo de compilación a través de una ruta relativa como ../../foo, asegúrate de que no esté excluido por .vercelignore.
Referencia
Rutas (matriz de Fase 2): /, /explorer, /hub, /schema,
/schema/[version], /docs, /docs/[[...slug]] (~36 slugs de documentación de
lib/doc-nav.ts). API: /api/waitlist (POST agregar, GET lectura de administrador),
/api/stars.
Selectores del formulario de correo electrónico (EarlyAccessForm.tsx): entrada de correo electrónico
input[type=email] / aria-label="dirección de correo electrónico" / .ea-input; enviar
button.ea-btn ("obtener acceso temprano" -> cargando -> éxito); honeypot oculto
input[name=company] (rellenarlo -> falso-éxito silencioso, nunca almacenado).
Lectura de administrador de la lista de espera: GET /api/waitlist con
Authorization: Bearer $WAITLIST_ADMIN_TOKEN. Respuesta: { ok: true, count: N, emails: [...] }.
Limpieza: ZREM waitlist deploy-verify-<marca de tiempo>@opentraces.ai.
Ruta de compilación de versión: src/opentraces/__init__.py > __version__ -> next.config.ts ->
process.env.NEXT_PUBLIC_APP_VERSION -> version.json servido estáticamente.