frontend-review-ci

フロントエンドレビュー — CI の最適化

フロントエンドプロジェクトの GitHub Actions CI を最適化します。目標は 中央値 ≤ 10 分、最大 ≤ 15 分 です。CI が速ければ、開発者は CI を信頼します。その信頼がラチェットを機能させます。

手順

1. scripts/audit-ci.sh --repo <client-repo> を実行します。
2. <client-repo>/.frontend-review/report/latest/raw/ci.json を読みます。
3. 実行時間が最も長い実行について、ステップ単位の所要時間を詳しく調べます。

   gh run view <run-id> --log | grep -E '^\d{4}-' | head -200
   

4. .github/workflows/ 以下の現在のワークフローを確認し、以下を記録します。
   • すべてのジョブ（lint、build、test、coverage など）で pnpm/npm ストアキャッシュを使用していますか？よくある見落としとして、test.yml にはキャッシュがあるものの、lint.yml と pages.yml にはないケースがあります。
   • actions/setup-node で cache: pnpm を使っていますか？それとも、pnpm ストア用の actions/cache ブロックを手動で設定していますか？どちらでも構いませんが、キーには hashFiles('**/pnpm-lock.yaml') を含める必要があります。
   • actions/cache で Playwright のブラウザーストア（~/.cache/ms-playwright）をキャッシュしていますか？
   • concurrency: ブロックはありますか？
   • vitest / playwright はシャーディングされていますか？
   • ジョブは不必要に needs: で直列化されていますか？
   • lint と typecheck は同じ直列ジョブにありますか？相互に依存していないため、別々の並列ジョブにする必要があります。

出力

<client-repo>/.frontend-review/report/latest/md/ci-analysis.md に以下を記載します。

• 現在の中央値 / 最大所要時間
• 代表的な失敗実行と成功実行における、所要時間が最も長い 3 つのステップ
• YAML パッチの行にそれぞれ対応付けた具体的な推奨事項（全面的な書き換えではありません）
• 推奨事項ごとに見込まれる効果

その後、ユーザーが gh pr create にコピーできる PR の説明文案を作成し、ブランチ名を ci/optimize とします。

開発イテレーションの所要時間目標

CI の遅さを診断する際の基準値として、以下のしきい値を使用してください。いずれかのステージが目標の 2 倍 を超える場合は、専用のボトルネック課題を作成します。

ステージ	目標	測定方法
HMR（編集 → 画面表示）	< 500 ms	Vite の --debug 出力
単体テスト — 単一ファイル	< 1 s	vitest / jest の出力
test:ci — 全テストスイート	< 1 分	CI のステップ所要時間
typecheck	< 30 s	CI のステップ所要時間
lint	< 30 s	CI のステップ所要時間
E2E — 1 シャード	< 50 s	CI のステップ所要時間
PR CI 合計（並列実行）	< 5 分	GitHub Actions の実時間
install（キャッシュヒット時）	< 15 s	CI のステップ所要時間
build	< 30 s	CI のステップ所要時間

PR CI 合計の目標は、最も重要な基準です。CI が 5 分を超えると、開発者は日常的に CI を回避するようになります。

ボトルネック特定の手順

1. 最近の実行のうち、所要時間が最も長いものからステップ単位の所要時間を取得します。

   gh run view <run-id> --log | grep -E '^\d{4}-' | head -200
   

2. DAG 内で最も遅いジョブを 1 つ特定します。並列グラフでは、最長経路のみが実時間を決定します。
3. そのジョブ内で、最も遅いステップを特定します。
4. PR 1 件につき変更は 1 つにします。複数の最適化をまとめると、回帰の原因を特定できなくなります。
5. 同じブランチで変更前後の実時間を測定し、効果を検証します。

典型的な最適化パターン

領域	よくある対策
install	pnpm / npm ストアのキャッシュキー、--frozen-lockfile、onlyBuiltDependencies の対象を絞る。すべてのワークフローファイルを確認してください。一部のジョブだけキャッシュされている部分的なキャッシュが、最もよくある見落としです。キャッシュなしの install は約 20～25 s ですが、キャッシュヒット時は約 2～3 s に短縮されます
lint + typecheck	相互依存がないため、2 つの並列ジョブに分割する。TS ファイルが約 170 個あるプロジェクトでは、これだけで lint ジョブの実時間を半分に短縮できます
typecheck	Project References による分割、skipLibCheck: true の設定、循環している型インポートの解消
lint	PR では lint-staged を使って変更ファイルのみを対象にし、リンター独自のインクリメンタルキャッシュを有効にする
vitest	isolate: false の設定、--pool のスレッド数の調整、coverage の対象からテストフィクスチャを除外する
Playwright	テスト量に応じたシャード数の調整、page.route() による外部 API のモック、フレーキーなテストを毎日実行するタグに移動する
ランナーのサイズ	上記の対策をすべて試した後の最終手段としてのみ、より大きなランナー（4 コア以上）を使用する

境界

• 実際に PR を作成したり、ブランチをプッシュしたりしないでください。説明文の下書きだけを作成してください。
• クライアントリポジトリのワークフロー YAML は変更しないでください。提案を確認した後、ユーザーが変更します。

参考資料

• チェックリスト：checklist/09-ci-optimization.md
• フェーズ：phase/week-1-ci-baseline.md
• テンプレート：templates/github-actions/ci.yml、templates/github-actions/e2e.yml