vercel-optimize

Vercel Optimize

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

基本方針: 不明な規則がある場合は references/doctrine.md を読んでください。

• メトリクス優先。推奨事項はリポジトリ全体の grep ではなく、Vercel の本番シグナルから始めます。
• 決定論的ゲート。scripts/gate-investigations.mjs が、どの項目を調査する価値があるかを判断します。
• 候補に紐づくスコープ。候補で指定されたファイル、またはルート内のインポートチェーンにあるファイルのみを読みます。
• バージョンを意識した引用。references/docs-library.json のみを使用します。無効な引用やバージョンが一致しない引用は削除されます。
• 顧客向けの文面。レポートやチャットの出力を書く前に、references/voice.md を読んでください。

前提条件

• vercel metrics、vercel usage、vercel contract、vercel api を備えた Vercel CLI v53 以降。
• 認証済みの CLI セッション: vercel login。
• リンク済みのアプリディレクトリ: vercel link。VERCEL_PROJECT_ID はプロジェクト設定の解決に役立ちますが、vercel metrics はディレクトリのリンクを必要とします。リンクまたは環境には、対象のプロジェクトの org/team/user スコープを含める必要があります。これにより、コレクターは 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 / 不明	デフォルトでブロック	ユーザーが限定的なプラットフォーム/コードのみの監査を受け入れる場合にのみ続行

サポートされていない場合は、スキャンやゲート処理の前に停止し、確認してください:

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?

ユーザーが続行を選択した場合は、--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 の場合は、次のプロンプトを使用してください:

I can't safely identify the Vercel project and account for this audit yet.

Please confirm the Vercel project name or ID and the team slug/name, or tell me it's under your personal account. Once confirmed, I'll relink or rerun collection against that exact scope before checking metrics.

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>
# add --team <team-id-or-slug> when known

• 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 を再利用できます。

照合では、ソース調査の前に、反証された候補を決定的に observation へ変換します:

• 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 に従い、JSON の推奨事項 1 件、または JSON の変更不要の所見 1 件を出力します。
• 提供された引用サブセット以外の 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 の各エントリについては、同じブリーフを topFailures を列挙した Previous attempt failed these checks セクションを付けて再実行します。再生成した出力は、引用を損なうことなく検証結果が改善した場合にのみ保持してください。

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/Storage を削減する。Workflow エンドポイントの経過時間からコスト削減を推測しないこと。
• ストリーミング、SSE、再開可能なチャット、その他意図的に長時間稼働するルートについては、関数の経過時間そのものを問題として扱わないこと。回避可能な初回バイト送信前の処理、高いアクティブ CPU、重複した呼び出し、またはユーザーに見える経路の外に移せるレスポンス後の処理、といった証拠を必要とすること。
• キャッシュを推奨する場合は、具体的なキャッシュポリシーを指定すること。
• 安全性が証明されない限り、安全でないレスポンスは動的なままにすること。対象は、認証に関わるパス、エラー、フォールバックレスポンス、コンテンツの欠落、無効なリクエスト、ジオロケーションやデバイスによって変化する出力、バージョン管理されていない動的 URL です。

signals.project に既に存在する事実（Fluid compute の状態、メモリティア、リージョン、関数内同時実行数、タイムアウト）について、「〇〇が有効になっているか確認してください」という推奨を決してしないこと。

スキャナールール

スキャナーの検出結果は補足的なものです。スキャナーが metadata.trafficIndependent === true を宣言していない限り、COLD-PATH または NO-ROUTE-MAPPING の注釈が付いた検出結果は除外してください。

トラフィック非依存の例: ミドルウェアのマッチャー、ソースマップ、React Compiler の設定、ビルド設定。ルートローカルのキャッシュやデータ取得パターンには、ルートレベルのトラフィックの証拠が必要です。

スキャナーのドキュメント: references/scanner-patterns.md。

顧客向けの最終的な用語

以下を使用します:

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

以下は避けます:

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

失敗時の文言

以下のメッセージを、販売文句や処理の詳細を加えずにそのまま使用してください。

過去14日間にトラフィックがない場合:

このプロジェクトは過去14日間に意味のあるトラフィックがないため、ルートレベルのメトリクスはまばらです。トラフィック非依存のスキャナーの検出結果とプロジェクト設定は引き続き確認できますが、トラフィックが蓄積されるまでルートの修正の優先順位付けはできません。

ルートレベルのメトリクスが利用できない場合:

references/observability-plus.md にある逐語的な選択肢テンプレートを使用してください。コードのみのモードに黙って切り替えないでください。Observability Plus を有効にしてメトリクスに基づく監査を再実行するか、制限付きのコードのみの実行を受け入れるか、という2つの経路の選択肢を提示してください。

プロジェクトがリンクされていない場合:

このワークツリーは Vercel プロジェクトにリンクされていません。vercel link --yes --project <project-name-or-id> --cwd <app-dir> を実行してから、監査を再実行してください。チームが判明している場合は、--team <team-id-or-slug> を追加してください。

ほとんどのルートとファイルのマッピングが失敗した場合:

ルートインベントリがobservabilityで確認されたルートの半分未満にしか一致しませんでした。これはカスタムルーティングを使用するモノレポでよく見られます。一致できたものを表示しました。残りは「この実行では調査されていない」セクションに表示されます。