Implantar Site
Implante o site de marketing Next.js (web/site/) em produção na Vercel, mas trate-o
como uma meta, não como um comando único: corrija todos os bugs relacionados ao site no main,
implante-o, prove que funciona em produção em todas as páginas e no fluxo de captura de e-mail
em desktop e mobile, e continue corrigindo + reimplantando até que tudo esteja verde.
Contrato da meta
Execute esta skill como um loop fechado. Não declare sucesso apenas com uma implantação limpa na Vercel; um deploy pode ser bem-sucedido enquanto uma página retorna 500, um layout quebra no mobile, ou a escrita da lista de espera falha silenciosamente.
- DONE quando: todas as correções relacionadas ao site são commitadas e enviadas para
main, o deploy de produção foi bem-sucedido, cada rota abaixo retorna 200 e renderiza corretamente em desktop e mobile sem erros de console/rede, e o fluxo de captura de e-mail aceita um envio e o persiste (comprovado por leitura de admin), sem linhas de teste restantes. - NOT DONE (loop novamente) quando: qualquer rota falha ao renderizar, um layout quebra em um viewport, o console mostra erros, ou a captura de e-mail não faz o round-trip. Corrija na fonte, refaça o land, reimplante, reverifique.
- BLOCKED (pare e relate) quando: uma correção precisa de uma credencial/decisão que você não tem (ex.: KV store inativo, token de admin ausente, autenticação Vercel expirada), ou a mesma falha sobrevive a 3 tentativas de correção. Relate a falha exata + o que você tentou; não faça loop infinitamente.
Mantenha um breve registro contínuo de cada iteração (o que falhou, o que você mudou,
resultado da reverificação) para que o loop seja auditável. Se o usuário quiser isso como
um /goal persistente, aponte a meta para esta skill e use as mesmas condições DONE/BLOCKED.
O loop
Fase 0 Escopo e land reunir correções do site -> verificação local -> commit -> push main
Fase 1 Deploy build -> npx vercel@latest --prod (da raiz do repositório)
Fase 2 Verificar (prod) Workflow fan-out: rotas x viewports + captura de e-mail
Fase 3 Triagem algum vermelho? corrija na fonte -> volte para Fase 0
tudo verde? -> DONE
Contexto
- Projeto:
opentracesna Vercel (escopojayfareis-projects) - Framework: Next.js 16 (App Router)
- Diretório raiz: Vercel configurado com raiz em
web/site/ - Domínio: opentraces.ai (produção: https://opentraces.ai)
- Build:
next build(executa deweb/site/) - Versão: Leitura automática de
src/opentraces/__init__.pyno build vianext.config.ts - Captura de e-mail:
EarlyAccessFormenvia para/api/waitlist(Upstash/KV em prod). Renderiza em/(viaHubTeaser) e/hub. Veja a seção de Referência para seletores + leitura de admin.
Fase 0 — Escopo e land das correções do site
-
Encontre o que é relacionado ao site e não foi enviado. A árvore de trabalho geralmente contém uma mistura de alterações de site + não-site. Faça land apenas das correções do site aqui (o resto é uma preocupação separada).
git status --short web/site/ git status --short -- ':!web/site/' # alterações não-site, geralmente deixe-as git log --oneline origin/main..HEAD -- web/site/ # commits do site ainda não enviados -
Verificação local antes do land (portão). Execute o site contra o servidor de desenvolvimento já em execução e verifique a superfície alterada com agent-browser: claro + escuro, desktop + mobile, a interação específica que você mudou, mais console/rede limpos. Este é o portão pré-land; não cometa uma regressão visual (Se nenhum servidor de desenvolvimento estiver ativo,
cd web/site && npm run devem uma porta sobressalente, verifique e depois pare-o.) -
Build local (captura erros de tipo/build que o servidor de desenvolvimento esconde):
cd web/site && npm run buildCorrija qualquer falha de build antes de continuar.
-
Commit no main e push. Por convenção do projeto, faça commit diretamente no
main(não crie automaticamente um branch de recurso a menos que solicitado). Mantenha o commit escopo para a correção do site; co-autor do commit de acordo com a regra de rodapé do repositório.git add web/site/ # stage apenas as correções do site que você verificou git commit -m "fix(site): <o que mudou>" git push origin main
Fase 1 — Build & deploy
Implante da raiz do repositório (não web/site/), porque a Vercel resolve o
diretório raiz das configurações do projeto (rootDirectory=web/site). Executar
de dentro de web/site/ aninha o caminho duas vezes. Sempre fixe na versão mais recente da CLI
(npx vercel@latest).
cd /caminho/para/raiz/do/repo
rm -rf web/site/.next kb/app/.next # saída de build obsoleta; incha o upload
npx vercel@latest --prod --yes
NÃO use --archive=tgz (medido em 2026-06-26, CLI 54.x). --archive=tgz
compacta toda a árvore de trabalho e ignora .vercelignore, então carrega
.git-menos-nada-mais além de kb/, .otbox/, web/site/.next-test/, etc. —
um upload de ~3 GB / 1998 arquivos que leva minutos e uma vez travou por ~20 min em
"Extracting deployment files" na máquina de build (uma parada real de produção que encontramos).
O caminho padrão arquivo por arquivo em vercel@latest ao invés disso:
- respeita
.vercelignore→ ~628 arquivos / ~40 MB, - envia em ~2 s e atinge READY em ~60 s ponta a ponta,
- não atinge o
Error: Upload abortedque--archive=tgzfoi originalmente adicionado para evitar (isso foi um bug de endpoint brew 41.x;vercel@latesto corrigiu, então a solução alternativa agora é líquido negativo).
Se uma CLI futura regredir o caminho arquivo por arquivo e você precisar recorrer a
--archive=tgz, espere o arquivo de ~3 GB e uma extração de vários minutos (ocasionalmente
travando) — repita o deploy se ele travar na extração.
Capture a URL/id do deployment da saída; você fará referência a ela no relatório de verificação.
Dica: você pode verificar um deploy preview da Vercel primeiro (omitindo
--prod) e executar a Fase 2 contra a URL de preview antes de promover. Isso mantém os testes de captura de e-mail completamente fora da lista de produção.
Fase 2 — Verificar em produção (JIT harness via Workflow / ultracode)
Comprove que o site ativo funciona. Esta fase é um just-in-time harness: você (o planejador) escopo a execução para este deploy, a ferramenta Workflow (o runtime determinístico) a executa, e workers de navegador efêmeros cada um retorna contra um schema tipado. O estado intermediário vive nas variáveis do harness, não no seu contexto, então a matriz completa é executada sem preencher sua janela. Esta skill opta explicitamente pela orquestração do Workflow (ultracode).
O harness é empacotado e congelado ao lado desta skill:
verify-site-deploy.workflow.js. Não cole o script inline; execute o arquivo.
O que verificar
- Rotas (cada uma deve 200 + renderizar, sem erros de console/rede):
/,/explorer,/hub,/schema,/docs, mais uma verificação spot de páginas profundas:/schema/0.6.0,/docs/getting-started/installation,/docs/cli/commands,/docs/schema/trace-record. - Viewports: desktop
1440x900e mobile390x844(classe iPhone). Onde uma correção mexeu com theming, verifique também claro + escuro. - Por página: HTTP 200, conteúdo primário visível, sem overflow/clipping de layout no viewport, console limpo, sem requisições de rede falhas, navegação funciona.
- Captura de e-mail (seu próprio agente, veja abaixo).
Verificação de captura de e-mail (não polua a lista de produção)
/api/waitlist escreve em um armazenamento ativo e não tem endpoint DELETE, então seja
deliberado:
- Round-trip real (uma vez, desktop): envie um endereço taggado como
deploy-verify-<timestamp>@opentraces.ai. Espere HTTP 200{ok:true}e o botão mudando para o estado de sucesso. Confirme que foi persistido com a leitura de admin (GET /api/waitlist+Authorization: Bearer $WAITLIST_ADMIN_TOKEN), anotando a contagem antes/depois. Em seguida, limpe-o removendo essa linha do armazenamento (UpstashZREM), e releia para confirmar que a contagem voltou. Deixe a lista imaculada. - Caminho de dedup: envie o mesmo endereço duas vezes, espere "você já está na lista" com a contagem inalterada.
- Mobile + verificações repetidas de UI sem escrever: preencha o honeypot oculto
(
input[name=company]) no envio. O endpoint retorna um falso-sucesso silencioso e nunca armazena a linha, então você pode confirmar a UI de sucesso no mobile sem adicionar lixo. (Se você vir "sucesso" mas a contagem não se moveu, isso é o honeypot funcionando, não um bug.) - Se o endpoint retornar 503 ("waitlist is not configured"), o KV store não está conectado nesse deployment: isso é BLOCKED (problema de env/store), não uma correção de código. Relate.
Execute o harness
Invoque o artefato empacotado com a ferramenta Workflow. Escopo por deploy com
args (este é o passo de "planejamento" JIT):
Workflow({
scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
args: {
baseUrl: "https://www.opentraces.ai", // host canônico; ou uma URL de preview para manter e-mail fora de produção
changed: ["/hub", "/"], // rotas que este deploy mexeu -> verificação profunda; o resto é fumado
pagesOnly: false // true = pular a escrita de e-mail (validação somente leitura executa)
}
})
Isso retorna { base, scoped, failures, allGreen }. allGreen: true significa que a Fase 2
passou; caso contrário failures lista exatamente o que corrigir na Fase 3.
Como o harness aplica os primitivos JIT (veja
kb/docs/concept-jit-harnesses-generic.md):
- Classificar e rotear: se você passar
changed, essas rotas recebem uma verificação completa do navegador (console, overflow, screenshot); toda outra rota é apenas um statuscurlbarato. Fluxo de controle JS puro que o runtime possui, nenhum modelo no meio, então um deploy escopo permanece barato. - Um worker de varredura determinístico por viewport (2 workers, não ~18): cada um executa
um único lote bash fixo (
curl+ um conjunto limitado de chamadas agent-browser por rota) em um modelo barato (haiku) e retorna o JSON analisado. Sem prompt aberto "verificar tudo", então o modelo não pode fazer loop; cada lote abre uma sessão de navegador eclose --allnela, para que processos Chrome não se acumulem. (Validado em 2026-06-09: ~16s para uma varredura completa de viewport, 1 processo residual, vs. o design original por célula de 54 processos / 15+ min.) - Confirmação adversária independente: qualquer rota que uma varredura sinalizar como falha é re-verificada por um worker separado com uma sessão limpa (modelo padrão) que tenta reproduzi-la; uma falha sobrevive apenas se a confirmação também falhar, então um fumble do agent-browser não se mascara como um bug do site.
- Contratos tipados: todo worker retorna contra
PAGE_VERDICT/EMAIL_VERDICT, então os resultados se mesclam mecanicamente. - Captura de e-mail tem seu próprio worker que prova a escrita via uma leitura de admin independente e limpa a linha de teste (veja as regras de não poluição acima).
Para alterar a matriz, a política de profundidade ou o schema de veredito, edite o arquivo .js,
ele é a única fonte da verdade. Se a mudança for uma página e você não quiser
orquestração, você ainda pode executar a verificação dessa página sequencialmente com a
skill agent-browser na sessão principal.
Fase 3 — Triagem & iterar
Leia os failures do workflow:
- Vazio -> a meta foi alcançada. Relate: id/URL do deployment, rotas verificadas, viewports, round-trip de e-mail comprovado e limpo. DONE.
- Não vazio -> para cada falha, encontre a causa raiz no código fonte de
web/site/, corrija-a e volte para Fase 0 (verificação local -> commit -> push -> deploy -> reverificar). Re-execute a verificação escopo nas rotas que falharam primeiro, depois uma passagem completa quando estiverem verdes. - Após 3 tentativas malsucedidas na mesma falha, ou em um bloqueio de credencial/store/auth, pare e relate como BLOCKED com o erro exato e o que você tentou.
Registre cada iteração no log contínuo para que o loop seja auditável.
.vercelignore
Localização importa: o arquivo efetivo é o .vercelignore da raiz do repositório. Mesmo que
o Root Directory do projeto seja web/site, todo o repositório é enviado
(o build lê ../../src/opentraces/__init__.py e ../../skill/SKILL.md),
e o único .vercelignore que o upload arquivo por arquivo honra é o da
raiz do repositório — os padrões são correspondidos relativos à raiz do repositório. Um
web/site/.vercelignore é ignorado; não adicione um (verificado em 2026-06-26 via
npx vercel@latest --debug).
É uma lista de ignore positiva (diretórios enumerados explicitamente, não um
catch-all * com negações ! — negações são frágeis e quebram entre versões da CLI). Sem ele, o upload
inclui as árvores pesadas do repositório. As grandes que ele deve excluir
(cada uma foi um vazamento real que corrigimos):
kb/(~2.4 G),.claude/(~1.5 G),tests/(~1.4 G),.venv*/(~0.8 G).otbox/(~613 M de tarballs de snapshots)web/site/.next-test/(~98 M / 1000+ arquivos — note que**/.next/não corresponde ao sufixo-test, então.next-test/precisa de sua própria regra)web/viewer/,web/coming-soon/,web/metrics-worker/
Caveat:
.vercelignoreapenas filtra o caminho de upload arquivo por arquivo. A flag--archive=tgzo ignora (veja Fase 1 — outra razão para não usá-lo).
Para verificar sanidade do que seria enviado após editar .vercelignore, execute
npx vercel@latest --debug da raiz do repositório e leia a
linha Found N files … M required to upload, depois Ctrl-C — nenhum deploy completo necessário.
Um deploy de site saudável é ~628 arquivos, não ~2000.
Arquivos que NÃO devem ser ignorados (o build os lê no momento do build):
| Arquivo | Lido por | Propósito |
|---|---|---|
src/opentraces/__init__.py | next.config.ts | Detecção de versão para version.json |
skill/SKILL.md | lib/docs.ts (getSkillContent()) | Conteúdo de visualização da máquina nas páginas de documentação |
Se você adicionar um novo arquivo que o site lê no momento do build via um caminho relativo como
../../foo, garanta que ele não seja excluído por .vercelignore.
Referência
Rotas (matriz da Fase 2): /, /explorer, /hub, /schema,
/schema/[version], /docs, /docs/[[...slug]] (~36 slugs de docs de
lib/doc-nav.ts). API: /api/waitlist (POST add, GET admin read),
/api/stars.
Seletores do formulário de e-mail (EarlyAccessForm.tsx): input de e-mail
input[type=email] / aria-label="email address" / .ea-input; submit
button.ea-btn ("get early access" -> loading -> success); honeypot oculto
input[name=company] (preenchê-lo -> falso-sucesso silencioso, nunca armazenado).
Leitura de admin da lista de espera: GET /api/waitlist com
Authorization: Bearer $WAITLIST_ADMIN_TOKEN. Retorna um array JSON de inscrições ordenado por
score (ts). O token está em WAITLIST_ADMIN_TOKEN (no ambiente Vercel
jayfareis-projects, ou no arquivo local .env.local). Se falhar com 401/403,
verifique se o token ainda é válido.
Viewports: Desktop = 1440x900 (ou 1280x800 se a tela física for limitada).
Mobile = 390x844 (iPhone 14 Pro). Onde uma correção muda layout/padding/margins,
adicione uma verificação tablet 768x1024 — a maioria dos quebras de layout do site
aparece nesse viewport antes do desktop.
SKILL.md corresponde ao arquivo de habilidade implantável. Para alterações, edite
skill/deploy-site/SKILL.md na fonte.