ci-speedup

CI の高速化

変更を push してから deploy するまでの間に、どのステージで待ち時間が発生しているかを特定し、数値に基づいてそのステージを改善して、何を変更したかと、いつ再確認するかを記録します。

• 対象： 変更が push から deploy までのどこで待っているかの測定、パイプラインのクリティカルパス、各レーンにおけるチェックの配置と必須チェックのセット、マージキューのサイズ設定またはマージ後の設計、main の健全性の検出・原因の特定・リバート、リバート・再マージ・修復を人間の介入なしに行うエージェント型マージループ、フレークのポリシー、deploy のスループット、マージ済み変更あたりのコスト、台帳。
• 対象外：
  • 1 つの PR のビルド失敗、競合、または単発の再実行（pr-babysitter）
  • パッケージのリリース（autoship）
  • どのチェックを設けるか、ルールの適用、フックの配線、保護対象のパス、または無人エージェントジョブのサンドボックスルール（codebase-architecture）。このスキルが担当するのは、そうしたジョブをディスパッチし、リバート・マージ・deploy を決定するマージコントローラーです
  • テストの削減（test-audit）
  • ワークフローの差分レビュー（tidy）
  • まだパイプラインがないリポジトリ（scaffold-cli、scaffold-nextjs）
  • 実行するエージェントの数、またはリポジトリのマージリスクポリシーの作成（このスキルはそのポリシーを参照しますが、作成はしません）

モデル

目的は、3つの予算と1つの厳格な上限の範囲内で、X = 1時間あたりにマージおよびデプロイされる変更数を最大化することです。

記号	予算
R	週あたりの main が赤になる時間（分）
C	マージされた変更1件あたりのランナー稼働時間（分）：PRの実行回数 × プッシュ回数、破棄された投機的実行を含むキューの実行回数、mainの実行、再実行、プッシュごとのレビューボット
F	プッシュから投稿者が対応できる判定までのp90時間。エージェントのコンテキストは待機中に劣化します

取り返しのつかない損害（破壊的なマイグレーション、インフラ、シークレットの漏えい）は、Xのコストがいくらであってもゼロに保ちます。

すべてのファイルで使う記号：λ = 到着率（マージ数／時間）；T = マージ経路のCI所要時間（分）；p = マージされたツリーでの失敗率（フレークを含む）；p_mb = ヘッドがグリーンだった場合のマージによる破損率；B = バッチサイズ；D = 投機的実行の深さ。

制約の特定。 PRごとに、オープン、準備完了、ヘッドがグリーン、承認、キュー登録、マージ、mainの判定、デプロイのタイムスタンプを取得します。各段階をWAITまたはWORKに分類します。レビューとキューでの待ち時間はWAITです。週あたりのキュー待ち時間が最も長い段階が制約となり、リトルの法則（WIP = λ × リードタイム）で計算を確認できます。その制約を活用し、他の段階をそれに従属させてから、制約を強化します。修正のたびに制約が移動するため、測定し直してください。CIが制約でないときにCI所要時間を短縮するのは、スループットではなくコストを下げる施策です。

パイプラインの所要時間。 パイプラインが制約となっている場合、その実時間はジョブの合計ではなく、依存するジョブのうち最も遅い連鎖で決まります。その連鎖からランナー稼働時間を節約する施策はCを下げますが、Fは下げません。台帳にはコスト削減として記録します。

レーンと配置。 各チェックは1つのレーンで実行します。投稿者のプッシュ前、PRゲート（正確なヘッド）、マージ経路（マージされたツリー。そうでなければ実行しない）、マージ後のmain（実行をまとめ、オートリバートを駆動）、デプロイ前（正確なアーティファクト）、または夜間（マージ判定には使用しない）です。各チェックの配置は、次の順に問いかけて決めます。出荷された場合に取り返しがつかないか（マージ前にブロックし、人間の確認レベルにする）；マージで破損しうるか、つまり他のPRとマージしたときに結果が変わりうるか（マージされたツリーで実行し、そうでなければPRヘッドでのみ実行する）；決定的か（オートリバートを駆動できるのはこれだけ）；そして、検出できる問題に対してTをどれだけ増やすか。分類表とYAMLはreferences/lanes.mdにあります。

デフォルトのアーキテクチャ：マージキューなし。 PRは、それぞれの正確なヘッドに対する証拠に基づいてマージします。mainはマージ後にまとめた実行で自らを検証するため、各実行はバッチになります。決定的な失敗は二分探索し、コードでリバートします。再度の取り込み、競合、フレークの修正は、新しいタスクとしてエージェントに割り当てます。デプロイは最新の検証済みコミットを対象にします。高リスクのレベル、キルスイッチ、サンプル監査は人間が担当します。これはAnthropicが1日あたり30,000件以上のマージで運用している形で、各バッチが1コミットとなる低ボリュームでも機能します。「ブランチを最新に保つことを必須にする」や「マージ前にmainがグリーンであることを必須にする」とは決して答えないでください。どちらもマージを直列化します。赤字予算を満たせない、デプロイを検証済みコミットに限定できない、破損の大半が非決定的である、またはmainをリバートできない場合に限り、マージキューに切り替えます。切り替え条件とキューの計算方法はreferences/merge-path.mdに、GitHubでの実装はassets/github/およびreferences/github-build.mdにあります。

参考ファイル

ファイル	読むタイミング
references/flow.md	ステップ 1、または PR がどこで待機しているかをユーザーが尋ねた場合：ステージの定義、WAIT と WORK の違い、リトルの法則、健全性メトリクス、マージ済み変更あたりのコスト、ci-flow.sh の出力の読み方
references/measuring.md	パイプラインの所要時間が制約になっている場合、またはステップ 5 で実行後のクレジットを計上する場合：実行、ジョブ、ステップの所要時間、3 つの比率、クリティカルパス、merge_group の実行、失敗と再実行の割合、キュー時間、実行後のルール
references/levers.md	所要時間を短縮する手段を選ぶ場合：セットアップ、実行、ツールチェーン、イメージビルドの手段、それぞれに必要な条件、落とし穴
references/lanes.md	チェックを配置する場合、on:、if:、needs:、concurrency: を編集する場合、必須チェックを変更する場合、何もチェックしていないのに成功するゲートの場合
references/merge-path.md	条件の切り替えがマージキューを必要とするかどうか、キューのサイズ調整、滞留したキュー、除外、競合、マージポリシー
references/main-health.md	main が赤い場合、または検出、原因特定、自動リバート、再ランディングを設計する場合
references/merge-loop.md	エージェント型マージシステムを設計する場合：コードが判断することとエージェントが修復すること、マージ後のバッチ処理、エージェントタスクの契約、自律性の段階、ループの健全性、エージェントの実行環境（Claude in Actions、eve、Devin）。main-health.md と bots.md も併せて読んでください
references/github-build.md	GitHub にループをインストール、または適応させる場合：Anthropic の設計をルールセットとワークフローに対応づける方法、セットアップの順序、コントローラーの状態管理、チェックアウトのコスト、インストールの検証
assets/github/	github-build.md が .github/ にインストールするテンプレート：merge-loop.json、loop.sh コントローラー、Managed Agents のエージェントと環境、および pr、main-verify、merge-loop、agent-task、deploy、superfan、audit-sample の各ワークフローと、ルールセットおよび CODEOWNERS
references/bots.md	リバート、修復、再キューイング、再ランディングなど、書き込みを行うボットを構築、変更する場合
references/flakes.md	断続的な失敗、再試行または隔離のポリシー、バッチ処理や二分探索の前
references/deploy.md	デプロイが制約になっている場合、またはデプロイがマージに遅れている場合
references/ledger.md	ステップ 6：台帳、フローメトリクスの推移、マージパスの意思決定記録、指示ファイルの行
scripts/ci-flow.sh	ステップ 1：制約行を含む、マージ済み PR のステージごとの中央値、p90、週あたり分数。--since、--base、--workflow、--environment、--json
scripts/ci-timings.sh	ステップ 2、パイプライン：1 回の実行におけるジョブ、ステップ、クリティカルパス、または --runs N によるジョブごとの中央値、p90、失敗、再実行、キュー待ち時間。キューでの実行には --event merge_group
scripts/ci-health.sh	ステップ 2、main：main 上で赤くなったエピソード、最初に問題が発生した SHA と最後に正常だった SHA、週あたりの赤い時間、フレーク候補

すべてのスクリプトは読み取り専用で、--repo owner/name（または GH_REPO）を受け取り、--help で使用方法を表示します。evals/evals.json にはシナリオと、このスキルを変更する前後の比較が含まれています。タスク中に読み込まれることはありません。

ワークフロー

進捗を追跡するには、このチェックリストをコピーしてください：

CI speedup progress:
- [ ] Step 1: Find the constraint (per-stage WAIT and WORK minutes per week)
- [ ] Step 2: Measure the constraint stage (pipeline, merge path, main, or deploy)
- [ ] Step 3: Decide with numbers (predicted X, R, C; one option; its flip condition)
- [ ] Step 4: Change it on a branch; re-time locally; dry-run every bot
- [ ] Step 5: After-measurement from the branch's own runs or a bot replay
- [ ] Step 6: Ledger, decision record, instruction-file lines, re-measure date

ステップ 1：制約を見つける

デフォルトブランチを対象に scripts/ci-flow.sh を実行し、制約を一文で示します。どのステージか、WAIT と WORK のどちらか、週あたりの分数、次のステージとの比較を記載してください。対象を絞った依頼（1 つのスイート、1 つのジョブ）の場合は、ステップ 2 のパイプライン分岐に進みます。対象期間内のマージ済み PR が約 20 件未満の場合は、ワークフロー設定とユーザーが示した件数をもとに推定し、すべての数値に推定値であることを明記してください。

ステップ 2：制約となっている段階を測定する

• パイプライン： scripts/ci-timings.sh --runs 20 --workflow ci.yml を実行して、ジョブごとの中央値と p90 を測定し、次に単一実行形式で各ステップとチェーンを測定します。変更を提案する前に、クリティカルパス上のすべての時間をツールチェーン、ゲーティング、セットアップ、実行に分類します。
• マージパス： merge_group の実行から T、p、排除数を取得し、ステップ 1 の到着数から λ を取得します。
• メイン： scripts/ci-health.sh から、失敗エピソード、R、および同じ SHA でどのチェックが合格後に失敗したかを取得します。
• デプロイ： デプロイ時間とマージ時間を比較し、各デプロイに含まれるマージ数を確認します。

ステップ 3：数値に基づいて判断する

X、R、C の予測変化、推奨する選択肢を 1 つ、そして判断を覆す測定値を明記します。経過時間が短縮する一方でランナー時間が増える場合は、およその増加量と、リポジトリがその時間分の料金を負担するかどうかを記載します。

ステップ 4：ブランチで変更する

ワークフロー、テスト、ボットの設定を 1 つのブランチで編集し、プッシュせずに測定できるものはローカルで再計測します。シャードが失敗する変更も、それをスキップする理由ではなく、調査結果です。書き込みを行うボットはすべて、ステップ 2 の失敗エピソードを再生して、何を元に戻すか、修復するか、再キューするかを列挙し、ドライランします。マージループの構築：GitHub では、references/github-build.md のセットアップ順に従って assets/github/ をインストールし、merge-loop.json とセットアップアクションをリポジトリに合わせて調整します。まず使い捨てのリポジトリで検証し、レベル 0 で導入して、リプレイの数値に基づいてのみレベルを上げます。

ガードは維持します。変更検出、コンカレンシーグループ、マージチェック、デプロイゲートは、通常、過去のインシデントを受けて設けられています。削除せずに移動し、インシデントへの参照を記したコメントをガードの隣に残してください。

ステップ 5：測定後の結果を確認する

ブランチ自身の実行結果が測定後の値です。効果を認める前に、references/measuring.md の実行後のルールを適用します。予測と測定結果が異なる場合は、別の施策を追加する前に理由を突き止めてください。ユーザーが所有するリポジトリ設定の変更待ちとなる施策は、再測定日に測定後の値を取得し、その旨を台帳に記載します。制約が別の段階に移るか、残る選択肢にユーザー自身の判断が必要になるまで、ステップ 2 から 5 を繰り返します。

ステップ 6：台帳と意思決定記録

references/ledger.md に記載された形式に従い、次の内容をリポジトリのドキュメントに記録します。変更前の値、変更内容、実行 ID を含む変更後の値、フローメトリクスの推移行、判断を覆す条件を含む意思決定記録、選択しなかった選択肢とそれぞれの保留理由、再測定日です。レイアウトの後退を防ぐ指示を、指示ファイルに追加します。

権限と完了条件

次の操作は読み取り専用、ブランチ内で完結、または元に戻せるため、都度確認なしで実行できます。gh による読み取り、スクリプトの実行、ローカルでの再計測、作業ブランチのプッシュ、PR の作成（リバート PR を含む）。

次の操作にはユーザーの判断が必要です。いずれも費用が発生するか、他のすべての変更に適用される条件が変わるためです。

• 支出：有料ランナー、キューの同時実行数の増加、または従量課金プランでの推測実行深度の増加
• リポジトリ設定：ルールセット、必須チェック、マージキューの有効化
• GitHub App の作成とそのキーおよびモデルキーの保存、Managed Agents のエージェントと環境の作成、Claude Code Review の有効化、MERGE_LOOP_RUNG を 0 より上に引き上げること
• main への変更のマージ

完了とは、マージ可能な変更、実際の実行またはボットのリプレイによる測定後の数値、判断を覆す条件を含む意思決定記録、および再測定日を記載した台帳の行が揃っている状態です。

注意事項

• PR の CI が数分で成功し、その後レビューやマージを何時間も待つパイプラインをシャーディングしても、X は変わりません。パイプラインに手を加える前に、ci-flow.sh でオープンからデプロイまでの時間を測定してください。
• 修正後は制約となる箇所が移ります。修正したステージだけを再計測すると、X は横ばいのままなのに改善したように見えます。変更のたびに ci-flow.sh を再実行してください。
• main で cancel-in-progress: true を設定すると、後続の実行によってロールアウト途中の実行がキャンセルされ、マージ済みのコミットに判定が残りません。PR では、後からプッシュがあると自分の計測実行が破棄されます。PR でのみ後続の実行をキャンセルし、計測対象の実行が完了するまでプッシュを控えてください。
• turbo run、pnpm -r run、lerna run はスクリプトのないワークスペースをスキップするため、ルートでのコマンドが成功しても、それらについては何も証明されません。ワークスペースごとの出力を確認してください。
• ワークフローのステップがラッパースクリプトを呼び出している場合、ワークフローの行を編集しても何も変わりません。実際のコマンドはラッパーが実行するためです。再計測する前に、コマンドの実行箇所を探してください。

関連スキル

• 赤くなっている、競合している、または再実行が必要な PR が 1 件ある場合や、この作業で作成する PR を監視する場合は、pr-babysitter を使用します。
• パッケージのリリースとその CI には、autoship を使用します。
• 存在すべきチェック、ルールの適用、フックの配線、保護対象パス、無人のエージェントジョブが実行されるサンドボックスについては、codebase-architecture を使用します。
• テストスイートが遅い原因が、何も証明しないテストを抱えていることにある場合は test-audit を使用します。不要なテストの削減はそちらの担当であり、こちらは計測を担当します。
• このスキルで生成されたワークフローの差分をレビューするには、tidy を使用します。
• リポジトリにまだパイプラインがない場合は、scaffold-cli と scaffold-nextjs を使用します。このスキルは、新しいリポジトリにはないタイムスタンプを起点にします。