Vercel Optimize

Exécutez un audit d'optimisation Vercel centré sur l'observabilité. N'inspectez pas les fichiers sources tant que signals.json n'existe pas et qu'une barrière déterministe ne pointe vers une route, un fichier ou un paramètre de projet.

Doctrine fondamentale : consultez references/doctrine.md si une règle n'est pas claire.

• Métriques d'abord. Les recommandations partent des signaux de production Vercel, pas d'une recherche dans tout le dépôt.
• Barrières déterministes. scripts/gate-investigations.mjs décide ce qui mérite une investigation.
• Scope limité aux candidats. Ne lisez que les fichiers nommés par un candidat ou une chaîne d'imports locale à la route.
• Citations sensibles aux versions. Utilisez uniquement references/docs-library.json ; les citations invalides ou ne correspondant pas à la version sont supprimées.
• Copie client. Lisez references/voice.md avant de rédiger le texte du rapport ou la sortie de chat.

Prérequis

• Vercel CLI v53+ avec vercel metrics, vercel usage, vercel contract et vercel api.
• Session CLI authentifiée : vercel login.
• Répertoire d'app lié : vercel link. VERCEL_PROJECT_ID peut aider à résoudre la config du projet, mais vercel metrics nécessite toujours une liaison de répertoire.
• Node.js 20+.
• Observability Plus pour les recommandations soutenues par des métriques au niveau des routes.

Ne mettez jamais de jetons d'authentification dans les commandes shell. Ne tapez pas VERCEL_TOKEN=..., --token ... ou Authorization: Bearer ... dans les commandes qui pourraient être répétées dans le chat.

Support des frameworks

Le preflight lit package.json et définit les attentes avant la distribution des métriques.

Si non supporté, arrêtez-vous et demandez avant de scanner ou de gater :

Ce projet utilise <framework>. Vercel Optimize supporte les recommandations de code soutenues par les métriques pour Next.js, SvelteKit et Nuxt. Le support d'Astro est limité. Pour <framework>, je peux toujours exécuter un audit limité plateforme/scanner, mais les métriques Vercel au niveau des routes peuvent ne pas se mapper aux fichiers sources.

Voulez-vous que je continue avec l'audit limité, ou que j'arrête ici ?

Si l'utilisateur continue, réexécutez la collection avec --continue-unsupported-framework.

Répertoire de run

Utilisez un répertoire de run vierge pour chaque audit. Ne réutilisez pas les briefs, les résultats de sous-agent ou les rapports d'un run à l'autre.

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

Pipeline

1. Collecter, scanner et fusionner les signaux

Exécutez à partir du répertoire d'app lié ou passez --cwd quand le script le supporte. Gardez la sortie JSON séparée des logs stderr. Ne mélangez pas les flux.

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"

Les détails de collection, les schémas, les IDs de métriques et le comportement de dégradation se trouvent dans references/data-collection.md. Le registre des métriques est lib/queries.mjs ; gardez toutes les requêtes sur la fenêtre commune de 14 jours.

1.1 Arrêt sur les blocages

Vérifiez les blocages avant le gating :

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

Actions requises :

• frameworkSupportBlocker === "unsupported_framework" : utilisez le prompt unsupported-framework ci-dessus.
• observabilityPlusBlocker === null : continuez.
• no_traffic : dites à l'utilisateur que les métriques de routes sont éparses ; continuez seulement s'il accepte une sortie limitée.
• payment_required ou no_oplus_probe : affichez references/observability-plus.md textuellement et demandez.
• project_disabled : dites à l'utilisateur d'activer Observability Plus pour le projet ou d'accepter un audit limité.
• daily_quota_exceeded : arrêtez-vous et dites à l'utilisateur que le quota de requête Observability est épuisé ; réessayez après la réinitialisation UTC de minuit suivante, ou demandez si continuez avec un audit limité code uniquement.
• not_linked : liez le répertoire d'app, puis réexécutez l'étape 1. Si le chemin d'app et le projet sont connus :

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# ajoutez --team <team-id-or-slug> quand connu

• forbidden ou project_not_found : corrigez l'auth/scope de l'équipe. Ne proposez pas Observability Plus.
• all_failed_other : affichez le code d'erreur brut et demandez si continuer en mode limité code uniquement.

Ne tombez pas silencieusement en mode code uniquement. Si l'utilisateur accepte un audit limité, réexécutez la collection avec :

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

Puis scannez et fusionnez à nouveau.

2. Gater les candidats

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

Forme de la sortie :

• toLaunch : candidats au scope code à investiguer.
• platform : recommandations au scope projet/compte.
• gated : candidats ignorés, couverts ou disqualifiés qui doivent toujours apparaître dans le rapport.
• budget : budget des candidats et mode de sélection.

Le budget par défaut est de 6 candidats au scope code avec une barrière de diversité. Pour étendre :

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"

Docs candidats générés : references/candidates.md.

2.1 Demander le scope de l'audit si nécessaire

Avant la deep-dive, exécutez :

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

Si shouldAsk est false, continuez.

Si shouldAsk est true :

1. Imprimez exactChatMessage.body exactement comme retourné. Ne résumez pas, ne tronquez pas, ne réordonnez pas ni ne réécrivez.
2. Puis posez questionText en utilisant questionPayload quand l'hôte supporte les questions structurées.
3. Si l'utilisateur choisit un nombre différent, réexécutez le gate avec --max-candidates <choice>.

Ne mettez jamais l'aperçu long dans le champ de question. L'aperçu et la question sont deux surfaces distinctes.

2.2 Deep-dive et réconciliation

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 doit être le répertoire du projet lié pour que vercel metrics résout le bon projet/équipe.

La réconciliation convertit de manière déterministe les candidats réfutés en observations avant toute investigation de source :

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 Générer les briefs et investiguer

Listez le travail :

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

Générez un brief pour chaque entrée dans briefs-manifest.json.briefs. Le group peut être toLaunch ou platform ; ne générez pas seulement les briefs 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"

Utilisez briefs-manifest.json.briefs[].label pour les noms de workers visibles, par exemple Low cache-hit route on /docs/llm-digest/[...slug], pas toLaunch-7.

Règle de fan-out :

• 1-2 briefs : investiguer inline.
• 3+ briefs : spawner un sous-agent par brief quand l'hôte le supporte.
• Hôtes sans sous-agents : exécuter inline en série.

Contrat du sous-agent :

• Le brief est le prompt entier.
• Lisez seulement les fichiers listés dans le brief, plus les imports locaux à la route si nécessaire.
• Émettez une recommandation JSON ou une découverte JSON no-change en utilisant references/recommendations.md.
• Ne citez pas les URLs en dehors du sous-ensemble de citations fourni.
• Ne recommandez pas des fonctionnalités du framework indisponibles dans la version détectée.

Si un sous-agent se lance dans une grep dans tout le dépôt, le candidat est mal formé ; abandonnez ou abstenez-vous plutôt que d'élargir le scope.

2.4 Collecter les résultats

Enregistrez chaque résultat d'investigation brut dans $RUN_DIR/sub-agent-outputs/, puis collectez :

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

Le collecteur extrait JSON, ajoute en préfixe les enregistrements pré-résolus, applique l'ordre du manifest et échoue sur les valeurs candidateRef manquantes, dupliquées, inconnues ou ne correspondant pas.

3. Vérifier les recommandations

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

Ce script extrait les claims, vérifie fichiers/citations/version, évalue la qualité, applique les sanitizers, émet verifiedRecommendations, withheldRecommendations, renderableRecommendations et crée regenPlan pour les recommandations échouées ou non sûres.

Schéma des recommandations, règles de rédaction, ordre des sanitizers et règles de notation : references/recommendations.md. Règles de vérification : references/verification.md.

Pour chaque entrée regenPlan, réexécutez le même brief avec une section Previous attempt failed these checks listant topFailures. Conservez la sortie régénérée seulement si la vérification s'améliore sans vider les citations.

4. Rendre le rapport et le message 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"

Utilisez --debug-out "$RUN_DIR/debug.json" seulement pour développer la skill. Le Markdown client et la sortie de chat ne doivent pas exposer passRate, quality, sentiers de sanitizers, noms bruts de sous-agents ou d'autres champs d'implémentation.

Après le rendu, imprimez final-message.json.body textuellement et arrêtez-vous. N'ajoutez pas de surbrillances, notes de débogage, counts bruts, résumés de sous-agents ou explication supplémentaire. La dédup au moment du rendu, les caps plateforme et les drops de sécurité dure peuvent changer le count visible par le client, donc ne résumez jamais à partir de verify.json brut.

Structure du rapport et cadrage de l'impact : references/scoring.md.

Règles des recommandations

Chaque recommandation doit :

• Remonter à un candidat lancé, candidat plateforme, observation pré-résolue ou découverte de scanner vérifiée indépendante du trafic.
• Inclure des preuves de métriques observées depuis signals.json ou evidence.deepDive.
• Citer les fichiers vérifiés avec numéros de ligne quand du code est impliqué.
• Inclure au moins une citation autorisée applicable au framework/version détecté.
• Utiliser des nombres de performance observés précis.
• Utiliser uniquement des phrases de magnitude de coûts ; jamais d'économies $N visibles au client.
• Nommer une politique de cache spécifique quand recommander le caching.
• Garder les réponses non sûres dynamiques sauf si les preuves montrent qu'elles sont sûres à cacher : chemins sensibles à l'auth, erreurs, réponses fallback, contenu manquant, requêtes invalides, sortie variant selon géolocalisation/device et URLs dynamiques non versionnées.

Ne recommandez jamais « vérifiez que X est activé » pour des faits déjà présents dans signals.project, incluant le statut Fluid compute, le tier mémoire, les régions, la concurrence intra-fonction et le timeout.

Règles du scanner

Les découvertes du scanner sont supplémentaires. Abandonnez les découvertes annotées COLD-PATH ou NO-ROUTE-MAPPING sauf si le scanner déclare metadata.trafficIndependent === true.

Exemples indépendants du trafic : middleware matcher, source maps, config React Compiler, build settings. Les patterns de cache local à la route ou data-fetch ont besoin de preuves de trafic au niveau des routes.

Docs scanner : references/scanner-patterns.md.

Termes clients finals

Utilisez :

• recommendations ready
• observations from investigation
• investigated, no change recommended
• not investigated in this run

Évitez :

• sub-agent
• abstention
• passRate
• quality score
• gate
• LLM

Copie d'échec

Utilisez ces messages sans ajouter de copie de vente ou de détail de processus.

Pas de trafic dans les 14 derniers jours :

Ce projet n'a pas de trafic significatif dans les 14 derniers jours, donc les métriques au niveau des routes sont éparses. Je peux toujours vérifier les découvertes du scanner indépendantes du trafic et les paramètres du projet, mais je ne peux pas classer les fixes de routes jusqu'à l'accumulation du trafic.

Métriques au niveau des routes indisponibles :

Utilisez le modèle de choix textuellement dans references/observability-plus.md. Ne tombez pas silencieusement en mode code uniquement ; présentez le choix à deux voies : activez Observability Plus et réexécutez l'audit soutenu par les métriques, ou acceptez une exécution limitée code uniquement.

Le projet n'est pas lié :

Cet arborescence n'est pas liée à un projet Vercel. Exécutez vercel link --yes --project <project-name-or-id> --cwd <app-dir> et réexécutez l'audit. Si l'équipe est connue, ajoutez --team <team-id-or-slug>.

La plupart des correspondances route-vers-fichier ont échoué :

L'inventaire des routes a mis en correspondance moins de la moitié des routes vues dans l'observabilité. C'est courant dans les monorepos avec routage personnalisé. J'ai surfacé ce que je peux mettre en correspondance ; le reste apparaît dans la section « Not investigated in this run ».