Vercel Optimize (Vercel最適化)

Vercel Optimize（Vercel最適化）

観測可能性ファーストのVercel最適化監査を実行します。signals.jsonが存在し、決定的なゲートがルート、ファイル、またはプロジェクト設定を指し示すまで、ソースファイルを検査しないでください。

基本原則: ルールが不明瞭な場合は、references/doctrine.mdを参照してください。

• メトリクス優先: 推奨事項はVercelプロダクションシグナルから始まり、リポジトリ全体のgrepから始まるわけではありません。
• 決定的ゲート: scripts/gate-investigations.mjsが調査に値するものを決定します。
• 候補に限定されたスコープ: 候補によって指定されたファイル、またはルートローカルのインポートチェーンのみを読み取ります。
• バージョン対応の引用: references/docs-library.jsonのみを使用します。無効またはバージョンが一致しない引用は削除されます。
• 顧客向けコピー: レポートテキストやチャット出力を書く前に、references/voice.mdを読んでください。

前提条件

• Vercel CLI v53以上（vercel metrics、vercel usage、vercel contract、vercel apiコマンドが利用可能であること）。
• 認証済みのCLIセッション: vercel login。
• リンクされたアプリケーションディレクトリ: vercel link。VERCEL_PROJECT_IDはプロジェクト設定の解決に役立ちますが、vercel metricsは依然としてディレクトリリンクを必要とします。リンクまたは環境には、意図されたプロジェクトの組織/チーム/ユーザースコープが含まれている必要があります。これにより、コレクターはCLIセーフな--scopeを解決し、vercel metrics、vercel usage、vercel contractを同じアカウントで実行し続けることができます。
• Node.js 20以上。
• ルートレベルのメトリクスに基づく推奨を得るためのObservability Plus。

認証トークンをシェルコマンドに決して入れないでください。VERCEL_TOKEN=...、--token ...、またはAuthorization: Bearer ...をチャットにエコーバックされる可能性のあるコマンドに入力しないでください。

フレームワークサポート

事前チェックはpackage.jsonを読み取り、メトリクス展開前に期待値を設定します。

フレームワーク	ステータス	備考
Next.js App Router	サポート	最強のルートマッピング、スキャナー、プレイブック、引用
Next.js Pages Router	サポート	検出時はPages Routerのイディオムに限定
SvelteKit	サポート	src/routesファイルとSvelteKitスキャナー用のルートマッピング
Nuxt	サポート	ルートマッピングと汎用/プラットフォームチェック、フレームワーク固有の推奨は少なめ
Astro	制限付き	ルートマッピングと汎用チェック、フレームワーク固有の推奨は少なめ
Hono / Remix / 不明	デフォルトでブロック	ユーザーが制限付きのプラットフォーム/コード監査を受け入れる場合のみ続行

サポートされていない場合、スキャンやゲーティングの前に停止してユーザーに確認してください:

このプロジェクトは <framework> を使用しています。Vercel Optimizeは、Next.js、SvelteKit、Nuxt向けのメトリクスに基づくコード推奨をサポートしています。Astroのサポートは限定的です。<framework> の場合、制限付きのプラットフォーム/スキャナー監査を実行することは可能ですが、ルートレベルのVercelメトリクスがソースファイルにマッピングされない可能性があります。

制限付き監査を続行しますか、それともここで停止しますか？

ユーザーが続行する場合、--continue-unsupported-frameworkフラグを付けてコレクションを再実行してください。

実行ディレクトリ

監査ごとに新しい実行ディレクトリを使用してください。ブリーフ、サブエージェント出力、レポートを実行間で再利用しないでください。

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

パイプライン

1. シグナルの収集、スキャン、マージ

リンクされたアプリケーションディレクトリから実行するか、スクリプトがサポートしている場合は--cwdを渡してください。stdout JSONとstderrログは別々に保持し、ストリームを結合しないでください。

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"

コレクションの詳細、スキーマ、メトリクスID、および動作低下の動作については、references/data-collection.mdを参照してください。メトリクスレジストリはlib/queries.mjsです。すべてのクエリは共有の14日間ウィンドウに従ってください。

collect-signals.mjsは、リンクされたプロジェクトの所有者をcommandScope.cliScopeに解決し、Observability Plusをチェックする前に、解決されたアカウントが解決されたプロジェクトを読み取れることを確認します。後続のスクリプトは、--scopeを受け入れるすべてのVercel CLIコマンドに対してそのスコープを再利用します。同じスコープなしでvercel usage、vercel metrics、vercel contractを手動で実行しないでください。スコープなしの使用状況はユーザーの個人組織を報告する可能性があり、ルートメトリクスはチームプロジェクトからのものになります。

プロジェクトまたはスコープの解決が曖昧な場合、停止してユーザーにどのVercelプロジェクトとチーム/個人スコープを監査したいか確認してください。意図されたスコープを現在のvercel whoamiチームから推測しないでください。リンク、.vercel/repo.json内の正確なプロジェクト一致、またはVERCEL_PROJECT_ID + VERCEL_ORG_IDが意図されたアカウントを識別するまで、メトリクス、使用状況、または契約の収集に進まないでください。

PROJECT_SCOPE_UNRESOLVED、SCOPE_UNRESOLVED、またはPROJECT_SCOPE_MISMATCHには、次のプロンプトを使用してください:

この監査のVercelプロジェクトとアカウントを安全に特定できません。

Vercelプロジェクト名またはIDと、チームスラッグ/名前を確認してください。個人アカウント下にある場合はその旨をお知らせください。確認後、その正確なスコープに対して再リンクまたはコレクションを再実行してから、メトリクスを確認します。

1.1 ブロッカーによる停止

ゲーティングの前にブロッカーを確認してください:

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

必要なアクション:

• frameworkSupportBlocker === "unsupported_framework": 上記のサポート外フレームワーク用プロンプトを使用します。
• PROJECT_SCOPE_UNRESOLVED、SCOPE_UNRESOLVED、またはPROJECT_SCOPE_MISMATCH: 停止して、ユーザーが監査したいVercelプロジェクトとチーム/個人スコープを確認します。チームプロジェクトの場合は、vercel link --yes --project <project-name-or-id> --team <team-slug> の後に再実行します。個人プロジェクトの場合は、意図したユーザーアカウント下でリンクした後、または VERCEL_PROJECT_ID と VERCEL_ORG_ID の両方を設定した後に再実行します。
• observabilityPlusBlocker === null: 続行します。
• no_traffic: ルートメトリクスが不十分であることをユーザーに伝え、制限された出力を受け入れる場合のみ続行します。
• payment_required または no_oplus_probe: references/observability-plus.md をそのままレンダリングし、確認を求めます。
• project_disabled: ユーザーにプロジェクトのObservability Plusを有効にするか、制限された監査を受け入れるよう伝えます。
• daily_quota_exceeded: 停止して、Observabilityクエリのクォータが枯渇したことをユーザーに伝えます。次のUTC深夜のリセット後に再試行するか、制限されたコードのみの監査を続行するかを尋ねます。
• not_linked: アプリケーションディレクトリをリンクしてから、ステップ1を再実行します。アプリのパスとプロジェクトがわかっている場合:

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# チームがわかっている場合は --team <team-id-or-slug> を追加

• forbidden または project_not_found: 認証/チームスコープを修正します。Observability Plusを勧めないでください。
• all_failed_other: 生のエラーコードを表示し、制限されたコードのみモードで続行するかどうかを尋ねます。

黙ってコードのみモードにフォールバックしないでください。ユーザーが制限された監査を受け入れる場合、次のコマンドでコレクションを再実行します:

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

その後、再度スキャンとマージを実行します。

2. ゲート候補

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

出力の形状:

• toLaunch: 調査するコードスコープの候補。
• platform: プロジェクト/アカウントスコープの推奨事項。
• gated: スキップ、カバー済み、または不適格となった候補。レポートには依然として表示する必要があります。
• budget: 候補の予算と選択モード。

デフォルトの予算は、多様性ガードレール付きで6つのコードスコープ候補です。拡張するには:

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"

生成された候補のドキュメント: references/candidates.md。

2.1 必要な場合に監査範囲について確認

詳細調査の前に、以下を実行します:

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

shouldAskがfalseの場合、続行します。

shouldAskがtrueの場合:

1. exactChatMessage.bodyをそのまま出力します。要約、切り詰め、順序変更、または書き換えをしないでください。
2. 次に、ホストが構造化された質問をサポートしている場合は、questionPayloadを使用してquestionTextを尋ねます。
3. ユーザーが異なる数を選択した場合、--max-candidates <choice> を付けてゲートを再実行します。

長いプレビューを質問フィールドに絶対に入れないでください。プレビューと質問は別々のサーフェスです。

2.2 詳細調査と調整

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はリンクされたプロジェクトディレクトリである必要があります。これにより、deep-dive.mjsが同じプロジェクトリンクを検証し、フォローアップのvercel metrics呼び出しのためにsignals.json.commandScope.cliScopeを再利用できます。

調整では、ソース調査の前に、証明されなかった候補を決定論的に観測結果に変換します:

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 ブリーフの生成と調査

作業をリストアップします:

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

briefs-manifest.json.briefsのすべてのエントリに対して1つのブリーフを生成します。groupはtoLaunchまたはplatformになります。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"

表示名にはbriefs-manifest.json.briefs[].labelを使用します。例: Low cache-hit route on /docs/llm-digest/[...slug]（toLaunch-7ではありません）。

展開ルール:

• 1〜2ブリーフ: インラインで調査します。
• 3ブリーフ以上: ホストがサポートしている場合、ブリーフごとに1つのサブエージェントを起動します。
• サブエージェントがないホスト: インラインで逐次実行します。

サブエージェント契約:

• ブリーフ全体がプロンプトです。
• ブリーフにリストされたファイルと、必要な場合のルートローカルインポートのみを読み取ります。
• references/recommendations.mdを使用して、1つのJSON推奨事項または1つのJSON変更なしの発見を出力します。
• 提供された引用サブセット外のURLを引用しないでください。
• 検出されたバージョンで利用できないフレームワーク機能を推奨しないでください。

サブエージェントがリポジトリ全体のgrepに到達した場合、その候補は不適切です。スコープを広げるのではなく、ドロップするか棄権してください。

2.4 出力の収集

各生の調査結果を$RUN_DIR/sub-agent-outputs/に保存し、その後収集します:

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

コレクターはJSONを抽出し、事前解決されたレコードを先頭に追加し、マニフェストの順序を適用し、不足、重複、不明、または一致しないcandidateRef値がある場合は失敗します。

3. 推奨事項の検証

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

このスクリプトは主張を抽出し、ファイル/引用/バージョンの適合性を検証し、品質を評価し、サニタイザーを適用し、verifiedRecommendations、withheldRecommendations、renderableRecommendationsを出力し、失敗したまたは安全でない推奨事項のためのregenPlanを作成します。

推奨事項のスキーマ、記述ルール、サニタイザーの順序、および評価ルール: references/recommendations.md。検証ルール: references/verification.md。

regenPlanの各エントリに対して、Previous attempt failed these checksセクションとtopFailuresのリストを追加して同じブリーフを再実行します。引用を損なわずに検証が改善された場合のみ、再生成された出力を保持します。

4. レポートと最終メッセージのレンダリング

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"

--debug-out "$RUN_DIR/debug.json"はスキル開発時のみ使用してください。顧客向けのMarkdownおよびチャット出力では、passRate、quality、サニタイザートレイル、生のサブエージェント名、その他の実装フィールドを公開しないでください。

レンダリング後、final-message.json.bodyをそのまま出力し、停止します。ハイライト、デバッグノート、生のカウント、サブエージェントの要約、または追加の説明を追加しないでください。レンダリング時の重複排除、プラットフォームの上限、およびハードセーフティによる削除により、顧客から見える数が変わる可能性があるため、生のverify.jsonから決して要約しないでください。

レポートの構造と影響のフレーミング: references/scoring.md。

推奨事項ルール

すべての推奨事項は以下の条件を満たす必要があります:

• 起動された候補、プラットフォーム候補、事前解決された観測結果、または検証済みのトラフィックに依存しないスキャナー発見にトレース可能であること。
• signals.jsonまたはevidence.deepDiveからの観測されたメトリクス証拠を含むこと。
• コードが関係する場合は、行番号付きの検証済みファイルを引用すること。
• 検出されたフレームワーク/バージョンに適用される、許可された引用を少なくとも1つ含むこと。
• 正確な観測されたパフォーマンス数値を使用すること。
• コストの規模を示すフレーズのみを使用し、顧客向けの$N節約額は決して使用しないこと。
• Vercel Workflowランタイムエンドポイント（/.well-known/workflow/v1/*）の期間短縮を推奨しないこと。これらは、耐久性のあるステップ/フロー実行のための生成されたオーケストレーションルートであり、調査前にハードゲートする必要があります。
• Workflowの推奨事項では、変更される境界に名前を付ける必要があります。有効な例: 完了を待機する代わりに、耐久性のある処理をキューに入れてランIDを返す、ストリームの再生/クローズ/ロックを修正する、検証済みの過剰なWorkflow Stepsを削減する。