Scale Check — 実運用準備評価(7段階評価)
あなたは 読み取り専用のプランモード で /scale-check を実行しています。あなたの仕事は、以下の7つのスケーリングに関する質問に沿ってコードベースを検査し、優先順位が明確で、検証と修正の計画をユーザーの画面に表示することです。
対象範囲: $ARGUMENTS(空の場合はリポジトリ全体を監査します)。
絶対ルール(スキャン前に必読)
- 参照のみ、変更はしない: あなたは厳密に診断と計画のモードです。ファイルを作成、編集、削除してはいけません。データベースマイグレーション、状態を変更するコマンド、ネットワークリクエストを実行してはいけません。
- 発見事項は確認すべき手がかりであり、事実ではありません: 静的リポジトリ分析では、外部のクラウドダッシュボード、CDNルール、WAFポリシー、管理データベースの設定は確認できません。発見した問題はすべて、確定的なバグではなく、確認すべき手がかり として扱ってください。
- 常に正確な場所を引用すること: すべてのコードに関する手がかりには、
path/to/file:lineと、関連する特定のシンボルやクエリを含めてください。何かがコードベースに存在しない場合は、明示的に 「リポジトリ内では見つかりませんでした。ホスティング/クラウドプロバイダーで確認してください。」 と報告してください。 - 一度に一つずつ修正し、生存性から始める: 最終的な修正計画は、常に バックアップ(質問5) と レート制限(質問7) から始め、次に 共有キャッシュを介したプライベートデータの漏洩(質問6)、そして残りの質問を、成長するアプリで通常問題となる順序(インデックスとループ(Q1)、共有読み取り(Q2)、2インスタンスでの実行(Q3)、リクエスト内の重い処理(Q4)、パブリックアセットのキャッシュ(Q6の残り))で並べてください。
実行ワークフロー
フェーズ1: スタックの特定(高速パス)
7つの質問をチェックする前に、プロジェクトのスタックを素早く特定し、適切な場所を調べられるようにします。
- マニフェストとフレームワーク:
package.json、pyproject.toml、requirements.txt、go.mod、Cargo.toml、Gemfileを確認します。 - データベースとORM:
schema.prisma、Drizzleスキーマファイル、TypeORM/Sequelizeモデル、SQLAlchemy/Alembicファイル、Djangoのmodels.py、または生の.sqlマイグレーションファイルを特定します。 - エントリーポイントとルート: APIルート(
app/api/、pages/api/、src/routes/、controllers/、routers/、main.py、cmd/)を特定します。 - インフラと設定:
Dockerfile、docker-compose.yml、vercel.json、next.config.*、fly.toml、render.yaml、nginx.conf、.github/workflows/、README.mdを確認します。
フェーズ2: 7つの質問すべてを調査
以下の7つの質問それぞれについて、Glob、Grep、Read パスを実行します。どの質問もスキップしないでください。
7つの質問
質問1: ループ内のインデックスとクエリ
- カード形式(短縮版): 「データを検索または一覧表示するページ:カラムにインデックスが張られていますか?ループ内にクエリはありませんか?」
- 完全な診断質問: アプリケーションはどこでレコードの一覧表示、フィルタリング、ソート、検索を行っていますか?その基盤となるデータベースカラム(
WHERE、JOIN、ORDER BY、外部キー)はスキーマ内のインデックスでバックアップされていますか?また、エンドポイントがループ内でデータベースまたはAPIクエリを実行していませんか(N+1問題)?ページネーションなしで無制限の行を取得していませんか? - どこを、どのように調べるか:
- スキーマとクエリの比較: リスト/検索クエリ(
findMany、select、filter、WHERE、ILIKE、ORDER BY)をインデックス定義(@@index、index()、CREATE INDEX、db_index=True)と比較します。Prisma/SQLAlchemyは、明示的に宣言しない限り、外部キーやソートカラムに自動的にインデックスを張らないことが多いことに注意してください。 - I/Oを含むループ: ルートハンドラーとサービス関数で、
for (、for await、.map(async、forEach(async、またはイテレーション内でdb.、prisma.、supabase.、session.execute、fetch(を呼び出すリスト内包表記をgrepで検索します。 - 無制限の読み取り: リストエンドポイントが
take/limitの上限を強制しているか、単一のリクエストでテーブル全体をメモリにロードできるかを確認します。
- スキーマとクエリの比較: リスト/検索クエリ(
- リポジトリ外にある可能性があるもの(誤検出チェック):
- インデックスは、本番のSQLコンソールで手動で作成され、マイグレーションファイルにコミットされていない可能性があります。
- 小さなルックアップテーブル(例:50未満の静的なロールやカテゴリ)は、インデックスがなくてもボトルネックになりませんが、ユーザー生成データに対するN+1ループは問題になります。
質問2: 頻繁に実行される共有読み取り
- カード形式(短縮版): 「頻繁に実行され、すべてのユーザーに同じ結果を返す読み取りクエリ。」
- 完全な診断質問: ランディングページのフィード、商品カタログ、グローバル設定、リーダーボード、公開カウントなど、すべての訪問者に対して毎回まったく同じパブリックデータを計算または取得する高トラフィックの読み取りクエリが、メモリ、Redis/KV、またはフレームワークのデータキャッシュに結果をキャッシュせずに実行されていますか?
- どこを、どのように調べるか:
- ユーザー固有のパラメータ(
userId、sessionId、orgId)なしで、すべてのページ読み込みでプライマリデータベースにアクセスするパブリックルート、ホームページ、レイアウトローダー、グローバルミドルウェアを検査します。 - 高コストな集計(
COUNT(*)、SUM()、複数テーブル結合)がパブリックエンドポイントでリアルタイム実行されているか確認します。 - 既存のキャッシュプリミティブ(
unstable_cache、'use cache'、revalidate、Redisget/set、@lru_cache、Cache-Control: s-maxage)を探して、共有読み取りが既にラップされているかを確認します。
- ユーザー固有のパラメータ(
- リポジトリ外にある可能性があるもの(誤検出チェック):
- 上流のCDN(Cloudflare、CloudFront、Fastly)が、ダッシュボードのページルールを介してパブリックルート全体をエッジで既にキャッシュしている可能性があります。
質問3: 2つのコピーとしての実行(ステートレス性とローカルストレージ)
- カード形式(短縮版): 「アプリは2つのコピーとして実行できますか?また、1つのサーバーのメモリまたはディスクには何が保存されていますか?」
- 完全な診断質問: トラフィックが急増し、ロードバランサーの背後に2つ目のサーバーインスタンスを起動した場合(または自動スケーリングするサーバーレスインスタンスにデプロイした場合)、単一プロセスのRAMに状態が保存されたり、単一コンテナのローカルファイルシステムに書き込まれたりしているために、何が壊れますか?
- どこを、どのように調べるか:
- プロセス内メモリ状態: モジュールレベルの
new Map()、new Set()、グローバルな可変配列/オブジェクト、インメモリセッションストア(MemoryStore)、ローカルレート制限カウンター、またはすべてのユーザーが同じNode/Python/Goプロセスにヒットすることを前提としたプロセス内pub/sub(EventEmitter、ブリッジされていないWebSocketSet)をgrepで検索します。 - ローカルディスクへの依存: ローカルファイル書き込み(
fs.writeFile、fs.createWriteStream、open(..., 'w')、multer.diskStorage、/tmpまたは./uploadsストレージ)と、可変ランタイムデータに使用されるローカル組み込みデータベース(sqlite、better-sqlite3、.dbファイル)をgrepで検索します。 - プロセス内Cronジョブ: メインのWebサーバーエントリーポイント内で起動されている
node-cron、setInterval、APSchedulerを確認します。これらは、2つのインスタンスが同時に実行されると、重複したジョブを起動します。
- プロセス内メモリ状態: モジュールレベルの
- リポジトリ外にある可能性があるもの(誤検出チェック):
- TTL付きの読み取り専用キャッシュとして(またはPrisma/Stripeのような遅延シングルトンSDKクライアントとして)厳密に使用されるモジュールレベルの
Mapは、複数のインスタンス間で安全です。 - マウントされた永続ボリュームとスティッキーセッションを使用する単一VPSアプリは、意図的に単一ノードとして実行される場合があります。その場合は、壊れていると判断するのではなく、トレードオフを明確に指摘してください。
- TTL付きの読み取り専用キャッシュとして(またはPrisma/Stripeのような遅延シングルトンSDKクライアントとして)厳密に使用されるモジュールレベルの
質問4: Webリクエスト内の同期的な重い処理
- カード形式(短縮版): 「Webリクエストが、AI呼び出し、メール、ファイルなどの遅い処理を行う場所。」
- 完全な診断質問: HTTPリクエストが、応答を返す前に、LLM/AI生成呼び出し、トランザクションメールの送信、PDFの生成、画像/動画のリサイズ、大きなCSVの解析、複数のサードパーティWebhookの連鎖など、遅い、予測できない、または重い処理を待っている間、ユーザーの接続を開いたままにしている場所はどこですか?
- どこを、どのように調べるか:
- リクエスト開始から応答返却まで、
POST/PUTコントローラー、Server Actions、Webhookハンドラーをトレースします。 - クリティカルなリクエストパス内で、AI SDK(
openai、@anthropic-ai、@google/genai、ai)、メールプロバイダー(resend、nodemailer、sendgrid、postmark)、メディア/ファイルプロセッサー(sharp、ffmpeg、puppeteer、pdfkit)、または外部APIへのブロッキングawait呼び出しをgrepで検索します。 - プロジェクトにバックグラウンドキューまたは非同期ワーカーのセットアップ(
bullmq、inngest、trigger.dev、celery、sidekiq、waitUntil)があるかどうか、また、遅い呼び出しが実際にそれを使用しているか、バイパスしているかを確認します。
- リクエスト開始から応答返却まで、
- リポジトリ外にある可能性があるもの(誤検出チェック):
- ストリーミングAIエンドポイント(
streamText、SSE、チャンク応答)は、トークンをクライアントにストリーミングしている間、接続を開いたままにするように設計されています。これらは、リクエスト内で重い同期の前処理/後処理を行っている場合や、タイムアウト制限がない場合にのみフラグを立ててください。
- ストリーミングAIエンドポイント(
質問5: バックアップ、レプリカ、復元パス
- カード形式(短縮版): 「どのようなバックアップまたはレプリカが、どこに、どのくらいの頻度で存在し、どのように復元するか。リポジトリにない場合は、そのように明記する。」
- 完全な診断質問: どのような自動化されたデータベースおよびストレージのバックアップまたはレプリカが存在し、それらはどこに保存され、どのくらいの頻度で実行され、それらを復元するための文書化されテストされた手順はありますか?バックアップ設定がリポジトリに表示されない場合は、その旨を明示的に述べてください。
- どこを、どのように調べるか:
- インフラストラクチャファイル(
docker-compose.yml、Terraform.tf、Pulumi、CloudFormation、fly.toml、.github/workflows/、scripts/、Makefile、crontab)でpg_dump、mysqldump、sqlite3 .backup、wal-g、litestream、S3バックアップ同期、またはレプリカ設定を検索します。 README.md、CONTRIBUTING.md、docs/、runbooks/で、バックアップスケジュール、ポイントインタイムリカバリ(PITR)、または復元コマンドの記載を検索します。
- インフラストラクチャファイル(
- 質問5の必須ルール:
- 管理データベース(Supabase、Neon、RDS、PlanetScale、Railway、MongoDB Atlas)を使用する最新のアプリのほとんどでは、バックアップ設定はクラウドダッシュボードにあり、gitにはありません。
- リポジトリにバックアップ設定と復元手順が見つからない場合は、明確に次のように述べてください: 「リポジトリにバックアップ設定や復元ランブックは見つかりませんでした。データベースプロバイダーのダッシュボードで自動バックアップ/PITRが有効になっていることを確認し、保持期間を確認し、ステージングデータベースへのテスト復元を実行してください。」
質問6: パブリックアセットとプライベートデータのキャッシュ
- カード形式(短縮版): 「どのファイルがすべてのユーザーで同一であり、どのファイルを決してキャッシュしてはいけないか。」
- 完全な診断質問: すべてのユーザーで同一の静的ファイル(バンドル、フォント、パブリック画像、マーケティングページ)は、CDN/ブラウザエッジで積極的にキャッシュされるように設定されていますか?また、認証済みまたはユーザー固有の応答(アカウントデータ、ダッシュボード、請求、認証トークン)は、共有キャッシュに保存されないように厳密に保護されていますか?
- どこを、どのように調べるか:
- 危険なキャッシュリーク(P0リスク): 個人情報、セッション状態、またはプライベートJSONを返すルートが、
privateやno-storeなしでCache-Control: publicまたはs-maxageを設定していないか、またはフレームワークのルートキャッシュ(export const revalidate = ...、force-static)が、特定のユーザーのCookie/ヘッダーを読み取るルートで誤って有効になっていないかを確認します。 - キャッシュされていない静的アセット:
next.config.*、vercel.json、nginx.conf、Expressstatic()、S3/CDNアップロードヘルパーを確認し、静的アセットとユーザーアップロードされたパブリックメディアに不変または長期のCache-Controlヘッダーが設定されているかを確認します。
- 危険なキャッシュリーク(P0リスク): 個人情報、セッション状態、またはプライベートJSONを返すルートが、
- リポジトリ外にある可能性があるもの(誤検出チェック):
- Next.js、Remix、Viteなどのフレームワークは、リポジトリにカスタムヘッダーがなくても、デプロイ時に
/_next/staticや/assetsの下にあるビルドアセットに自動的にフィンガープリントを付け、キャッシュします。
- Next.js、Remix、Viteなどのフレームワークは、リポジトリにカスタムヘッダーがなくても、デプロイ時に
質問7: パブリックエンドポイントと有料エンドポイント(レート制限とコストガード)
- カード形式(短縮版): 「どのエンドポイントがパブリックであるか、または有料サービスを呼び出すか、また、1人のユーザーがそれらを呼び出せる頻度を制限するものはありますか?」
- 完全な診断質問: 認証なしで呼び出せるルート(ログイン、サインアップ、マジックリンク、パスワードリセット、公開検索、お問い合わせフォーム、Webhook)や、従量課金/有料サービス(LLM API、SMS/OTP、メール送信、ファイルストレージ、有料データAPI)をトリガーするルートはどれですか?また、コード内でIPごとまたはユーザーごとのレート制限、リクエスト本文サイズの上限、支出/トークン制限を強制するものは何ですか?
- どこを、どのように調べるか:
- 高リスクエンドポイントの棚卸し: すべてのパブリックな認証/フォームルートと、課金対象の外部APIを呼び出す、または大量のDB書き込みをトリガーするすべてのエンドポイントをリストアップします。
- レート制限の確認: 依存関係とミドルウェアでレート制限ライブラリ(
@upstash/ratelimit、express-rate-limit、rate-limiter-flexible、slowapi、django-ratelimit、rack-attack、golang.org/x/time/rate)をgrepで検索し、それらが実際にリスクの高いルートに適用されているかを確認します。 - 入力と支出の上限の確認: AIまたはファイルアップロードエンドポイントで、
max_tokens/maxOutputTokens、プロンプト長の検証(例:Zod.max())、ファイルサイズ制限が、プロバイダーを呼び出す前に強制されているかを確認します。
- リポジトリ外にある可能性があるもの(誤検出チェック):
- レート制限は、アプリケーションリポジトリの外部で、Cloudflare WAF、AWS API Gateway、Vercel Firewall、Nginxリバースプロキシなどを介して上流で強制されている場合があります。リポジトリ内に制限がない場合は、上流で確認するか、ミドルウェアに追加するための優先度の高い手がかりとしてフラグを立ててください。
出力形式(この計画を画面に表示)
以下のセクションを正確に使用してレポートを表示してください。トーンは直接的で、落ち着いて、実用的に保ちます。
1. スタックとスコープのスナップショット
- 検出されたスタック: [フレームワーク、言語、DB/ORM、ホスティング/インフラのヒント]
- スキャンされたスコープ: [リポジトリ全体または特定のパス]
- 注意事項: 「これらの発見事項は確認すべき手がかりであり、確定的なバグではありません。クラウドダッシュボードで設定されたインフラ(管理DBバックアップ、CDNルール、WAFレート制限)はgitには表示されません。」
2. 7つの質問のスコアカード
| # | 質問 | ステータス | 主な手がかり/観察結果 |
|---|---|---|---|
| Q1 | 検索/一覧のインデックスとループ内クエリ | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
| Q2 | 同じデータを返す頻繁な共有読み取り | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
| Q3 | 2つのコピーでの実行(メモリとディスクの状態) | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
| Q4 | Webリクエスト内の同期的な重い処理 | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
| Q5 | バックアップ、レプリカ、復元 | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
| Q6 | パブリックアセットとプライベートデータのキャッシュ | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
| Q7 | パブリック/有料エンドポイントのレート制限 | [確認すべき手がかり] / [カバーされている模様] | 1行の要約 |
3. 優先順位付けされた修正計画
各質問の結果を、絶対ルール#4で定義された優先順位順にリストします。各項目には以下を含めます:
- 問題(手がかり): 見つかったものの簡単な説明。
- 場所: ファイルパスと行番号。
- 確認方法: 開発者がこの手がかりを確定的なバグとして確認するために取るべき正確な手順。
- 提案される次のステップ: 手がかりが本物であることが確認された場合に誰かがコードに加えるであろう変更の1〜2文の説明。
4. スコープ外の注意事項(リポジトリ外の項目)
このセクションには、リポジトリにコードとして存在しないが、実運用準備には重要な項目をリストします。各項目に、「確認してください:」 という形式で、開発者が確認すべき正確な場所を示します。
- クラウドダッシュボードでの管理DBバックアップ設定
- CDN/エッジキャッシュルールとWAFレート制限ルール
- ロードバランサーのスティッキーセッション設定
- 外部シークレット管理と環境変数
- このスキャンがリポジトリ内で特定できなかったその他のインフラ設定。