Otimização Vercel

Execute uma auditoria de otimização Vercel com foco em observabilidade. Não inspecione arquivos de origem até que signals.json exista e um portão determinístico aponte para uma rota, arquivo ou configuração de projeto.

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

• Métricas primeiro. As recomendações começam com sinais de produção Vercel, não com grep em todo o repositório.
• Portões determinísticos. scripts/gate-investigations.mjs decide o que merece investigação.
• Escopo limitado ao candidato. Leia apenas arquivos nomeados por um candidato ou uma cadeia de importação local da rota.
• Citações cientes da versão. Use apenas references/docs-library.json; citações inválidas ou incompatíveis com a versão são removidas.
• Linguagem para o cliente. Leia references/voice.md antes de escrever o texto do relatório ou a saída do chat.

Quando Usar

• Use esta habilidade quando a tarefa corresponder a esta descrição: Auditar aplicativos Vercel implantados para problemas de custo e desempenho usando métricas, configuração de projeto, varreduras de código e recomendações cientes da versão.

Pré-requisitos

• Vercel CLI v53+ com vercel metrics, vercel usage, vercel contract e vercel api.
• Sessão CLI autenticada: vercel login.
• Diretório de aplicativo 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 pretendido da organização/equipe/usuário do projeto para que o coletor possa resolver um --scope seguro para a 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 em nível de rota.

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

Suporte a Frameworks

A verificação inicial lê package.json e define expectativas antes da expansão das métricas.

Se não suportado, pare e pergunte antes de escanear ou definir portões:

This project uses <framework>. Vercel Optimize supports metric-backed code recommendations for Next.js, SvelteKit, and Nuxt. Astro support is limited. For <framework>, I can still run a limited platform/scanner audit, but route-level Vercel metrics may not map back to source files.

Do you want me to continue with the limited audit, or stop here?

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

Diretório de Execução

Use um diretório de execução novo para cada auditoria. Não reutilize resumos, 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 aplicativo vinculado ou passe --cwd onde um script o suporta. Mantenha o stdout JSON separado dos logs 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.

…