Vercel Optimize

O que Vercel Optimize faz?

Execute uma auditoria de otimização da Vercel focada em observabilidade. Não inspecione arquivos fonte até que signals.json exista e um gate determinístico aponte para uma rota, arquivo ou configuração do projeto.

Doutrina central: leia references/doctrine.md se alguma regra não estiver clara.

• Métricas primeiro. As recomendações partem de sinais de produção da Vercel, não de grep no repositório inteiro.
• Gates determinísticos. scripts/gate-investigations.mjs decide o que merece investigação.
• Escopo vinculado a candidatos. Leia apenas arquivos nomeados por um candidato ou por uma cadeia de importação local à rota.
• Citações com ciência de versão. Use apenas o references/docs-library.json; citações inválidas ou com versão incorreta são removidas.
• Cópia do cliente. Leia references/voice.md antes de escrever texto de relatório ou saída de chat.

Pré-requisitos

• Vercel CLI v53+ com vercel metrics, vercel usage, vercel contract e vercel api.
• Sessão CLI autenticada: vercel login.
• Diretório de aplicação vinculado: vercel link. VERCEL_PROJECT_ID pode ajudar a resolver a configuração do projeto, mas vercel metrics ainda requer vinculação de diretório. O link ou ambiente deve incluir o escopo de org/equipe/usuário do projeto pretendido para que o coletor possa resolver um --scope seguro para CLI e manter vercel metrics, vercel usage e vercel contract na mesma conta.
• Node.js 20+.
• Observability Plus para recomendações baseadas em métricas de nível de rota.

Nunca coloque tokens de autenticação em comandos shell. Não digite VERCEL_TOKEN=..., --token ... ou Authorization: Bearer ... em comandos que possam ser ecoados no chat.

Suporte a Frameworks

A verificação prévia lê package.json e define expectativas antes da coleta de métricas.

Framework	Status	Notas
Next.js App Router	suportado	mapeamento de rota mais forte, scanners, playbooks, citações
Next.js Pages Router	suportado	limitado a expressões do Pages Router quando detectado
SvelteKit	suportado	mapeamento de rota para arquivos src/routes e scanner SvelteKit
Nuxt	suportado	mapeamento de rota mais verificações genéricas/de plataforma; menos recomendações específicas do framework
Astro	limitado	mapeamento de rota mais verificações genéricas; menos recomendações específicas do framework
Hono / Remix / desconhecido	bloqueado por padrão	continue apenas se o usuário aceitar uma auditoria limitada de plataforma/código

Se não for suportado, pare e pergunte antes de escanear ou aplicar gate:

Este projeto usa <framework>. O Vercel Optimize suporta recomendações de código baseadas em métricas para Next.js, SvelteKit e Nuxt. O suporte para Astro é limitado. Para <framework>, ainda posso executar uma auditoria limitada de plataforma/scanner, mas as métricas de rota da Vercel podem não mapear de volta para arquivos fonte.

Você deseja que eu continue com a auditoria limitada, ou parar por aqui?

Se o usuário continuar, execute novamente a coleta com --continue-unsupported-framework.

Diretório de Execução

Use um novo diretório de execução para cada auditoria. Não reutilize briefings, saídas de subagentes ou relatórios entre execuções.

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

Pipeline

1. Coletar, escanear e mesclar sinais

Execute a partir do diretório de aplicação vinculado ou passe --cwd onde um script suportar. Mantenha o JSON de stdout separado dos logs de stderr. Não combine fluxos.

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"

Detalhes da coleta, esquemas, IDs de métricas e comportamento de degradação estão em references/data-collection.md. O registro de métricas é lib/queries.mjs; mantenha todas as consultas na janela compartilhada de 14 dias.

collect-signals.mjs resolve o proprietário do projeto vinculado para commandScope.cliScope e verifica se a conta resolvida pode ler o projeto resolvido antes de verificar o Observability Plus. Scripts downstream reutilizam esse escopo para cada comando da Vercel CLI que aceita --scope. Não execute vercel usage, vercel metrics ou vercel contract manualmente sem o mesmo escopo; uso sem escopo pode relatar a organização pessoal do usuário enquanto as métricas de rota vêm do projeto da equipe.

Se a resolução do projeto ou escopo for ambígua, pare e pergunte ao usuário qual projeto Vercel e escopo de equipe/pessoal ele deseja auditar. Não infira o escopo pretendido a partir da equipe atual do vercel whoami, e não prossiga com a coleta de métricas, uso ou contrato até que o link, uma correspondência exata de projeto em .vercel/repo.json ou VERCEL_PROJECT_ID + VERCEL_ORG_ID identifiquem a conta pretendida.

Use este prompt para PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED ou PROJECT_SCOPE_MISMATCH:

Ainda não consigo identificar com segurança o projeto Vercel e a conta para esta auditoria.

Por favor, confirme o nome ou ID do projeto Vercel e o slug/nome da equipe, ou me diga que está sob sua conta pessoal. Uma vez confirmado, vou religar ou executar novamente a coleta para esse escopo exato antes de verificar as métricas.

1.1 Parar em bloqueadores

Verifique bloqueadores antes de aplicar gate:

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

Ações necessárias:

• frameworkSupportBlocker === "unsupported_framework": use o prompt de framework não suportado acima.
• PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED ou PROJECT_SCOPE_MISMATCH: pare e pergunte qual projeto Vercel e escopo de equipe/pessoal o usuário deseja auditar. Para projetos de equipe, execute novamente após vercel link --yes --project <project-name-or-id> --team <team-slug>; para projetos pessoais, execute novamente após vincular sob a conta de usuário pretendida ou após definir VERCEL_PROJECT_ID e VERCEL_ORG_ID.
• observabilityPlusBlocker === null: continue.
• no_traffic: informe ao usuário que as métricas de rota são esparsas; continue apenas se ele aceitar saída limitada.
• payment_required ou no_oplus_probe: renderize references/observability-plus.md literalmente e pergunte.
• project_disabled: informe ao usuário para ativar o Observability Plus para o projeto ou aceitar uma auditoria limitada.
• daily_quota_exceeded: pare e informe ao usuário que a cota de consulta do Observability foi excedida; tente novamente após a reinicialização da meia-noite UTC seguinte, ou pergunte se deseja continuar com uma auditoria limitada apenas de código.
• not_linked: vincule o diretório da aplicação e execute novamente a Etapa 1. Se o caminho da aplicação e o projeto forem conhecidos:

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# adicione --team <team-id-or-slug> quando conhecido

• forbidden ou project_not_found: corrija o escopo de autenticação/equipe. Não ofereça o Observability Plus.
• all_failed_other: mostre o código de erro bruto e pergunte se deseja continuar no modo limitado apenas de código.

Não volte silenciosamente para o modo apenas de código. Se o usuário aceitar uma auditoria limitada, execute novamente a coleta com:

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

Em seguida, escaneie e mescle novamente.

2. Gate de candidatos

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

Forma de saída:

• toLaunch: candidatos de escopo de código a serem investigados.
• platform: recomendações de escopo de projeto/conta.
• gated: candidatos ignorados, cobertos ou desqualificados que ainda devem aparecer no relatório.
• budget: orçamento de candidatos e modo de seleção.

O orçamento padrão é de 6 candidatos de escopo de código com um guard rail de diversidade. 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 gerados: references/candidates.md.

2.1 Perguntar sobre o escopo da auditoria quando necessário

Antes do mergulho profundo, execute:

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

Se shouldAsk for falso, continue.

Se shouldAsk for verdadeiro:

1. Imprima exactChatMessage.body exatamente como retornado. Não resuma, trunque, reordene ou reescreva.
2. Em seguida, pergunte questionText usando questionPayload quando o host suportar perguntas estruturadas.
3. Se o usuário escolher um número diferente, execute novamente o gate com --max-candidates <escolha>.

Nunca coloque a prévia longa dentro do campo de pergunta. A prévia e a pergunta são superfícies separadas.

2.2 Mergulho profundo e reconciliação

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 deve ser o diretório do projeto vinculado para que deep-dive.mjs possa verificar o mesmo link de projeto e reutilizar signals.json.commandScope.cliScope para quaisquer chamadas vercel metrics de acompanhamento.

A reconciliação converte deterministicamente candidatos refutados em observações antes de qualquer investigação de origem:

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 Gerar briefings e investigar

Liste o trabalho:

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

Gere um briefing para cada entrada em briefs-manifest.json.briefs. O group pode ser toLaunch ou platform; não gere apenas briefings 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"

Use briefs-manifest.json.briefs[].label para nomes visíveis de workers, por exemplo Rota com baixo acerto de cache em /docs/llm-digest/[...slug], não toLaunch-7.

Regra de distribuição:

• 1-2 briefings: investigue inline.
• 3+ briefings: spawn um subagente por briefing quando o host suportar.
• Hosts sem subagentes: execute inline serialmente.

Contrato do subagente:

• O briefing é o prompt inteiro.
• Leia apenas os arquivos listados no briefing, mais importações locais de rota quando necessário.
• Emita uma recomendação JSON ou uma constatação JSON de nenhuma alteração usando references/recommendations.md.
• Não cite URLs fora do subconjunto de citações fornecido.
• Não recomende recursos do framework indisponíveis na versão detectada.

Se um subagente buscar grep no repositório inteiro, o candidato está malformado; descarte ou abstenha-se em vez de ampliar o escopo.

2.4 Coletar saídas

Salve cada resultado bruto de investigação em $RUN_DIR/sub-agent-outputs/, depois colete:

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

O coletor extrai JSON, pré-anexa registros pré-resolvidos, aplica a ordem do manifesto e falha em valores candidateRef ausentes, duplicados, desconhecidos ou incompatíveis.

3. Verificar recomendações

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 extrai alegações, verifica a adequação de arquivos/citações/versão, classifica a qualidade, aplica sanitizadores, emite verifiedRecommendations, withheldRecommendations, renderableRecommendations e cria regenPlan para recomendações com falha ou inseguras.

Esquema de recomendação, regras de escrita, ordem de sanitizadores e regras de classificação: references/recommendations.md. Regras de verificação: references/verification.md.

Para cada entrada em regenPlan, execute novamente o mesmo briefing com uma seção A tentativa anterior falhou nestas verificações listando topFailures. Mantenha a saída regenerada apenas se a verificação melhorar sem remover citações.

4. Renderizar relatório e mensagem 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"

Use --debug-out "$RUN_DIR/debug.json" apenas ao desenvolver o skill. O Markdown do cliente e a saída do chat não devem expor passRate, quality, rastros de sanitizadores, nomes brutos de subagentes ou outros campos de implementação.

Após a renderização, imprima final-message.json.body literalmente e pare. Não adicione destaques, notas de depuração, contagens brutas, resumos de subagentes ou explicações extras. A deduplicação em tempo de renderização, limites de plataforma e quedas de segurança rígida podem alterar a contagem visível ao cliente, portanto, nunca resuma a partir do verify.json bruto.

Estrutura do relatório e estruturação de impacto: references/scoring.md.

Regras de Recomendação

Cada recomendação deve:

• Rastrear até um candidato lançado, candidato de plataforma, observação pré-resolvida ou constatação de scanner verificada independente de tráfego.
• Incluir evidência de métrica observada de signals.json ou evidence.deepDive.
• Citar arquivos verificados com números de linha quando o código estiver envolvido.
• Incluir pelo menos uma citação permitida que se aplique ao framework/versão detectado.
• Usar números de desempenho observados precisos.
• Usar apenas frases de magnitude de custo; nunca economias $N voltadas ao cliente.
• Não recomendar reduções de duração para endpoints de runtime do Vercel Workflow (/.well-known/workflow/v1/*). Estas são rotas de orquestração geradas para execução de etapas/fluxos duráveis e devem ser bloqueadas com rigidez antes da investigação.
• Recomendações de Workflow devem nomear o limite que está sendo alterado. Exemplos válidos: enfileirar trabalho durável e retornar um ID de execução em vez de aguardar a conclusão, corrigir repetição/fechamento/travamentos de stream ou reduzir Etapas/S de Workflow excessivo verificado.

Scripts e Referências

Scripts locais e documentação de referência:

• scripts/collect-signals.mjs — Busca dados de métricas e uso da Vercel.
• scripts/scan-codebase.mjs — Escaneia o código-fonte do repositório.
• scripts/merge-signals.mjs — Mescla […] truncado para tradução