ci-optimize

CI の最適化

変更する前に、GitHub Actions の待ち時間を測定します。必須チェック、成果物、失敗時の動作を維持してください。

基本方針

鉄則： 具体的な変更を提案する前に、ベースラインを記録します。

破壊的なクリーンアップ、有料インフラの利用、依存関係のインストール、ソースの編集、リモートへのディスパッチを行うには、明示的な承認が必要です。

危険信号 — 次のことに気づいたら、作業を止めてください。

• 速度向上を示すために、チェック、成果物、ワークロード、または失敗経路を削除する。
• 再実行、一部のジョブページ、または変更された検証契約が主要な対象群に含まれる。
• ローカルでの結果やゼロの終了ステータスを、CI の比較の代わりに使用する。

正当化	問題点	必須の対応
「キャッシュの変更は明らかなので、すぐ適用できます。」	測定しても変更が承認されたことにはなりません。	計画を提示して、承認を待ちます。
「並列ジョブの所要時間を足せばよいです。」	指標は、選択したジョブのうち最も遅い完了時点で終了します。	実行の作成時点から測定します。
「同じワークフローでの再実行なので、比較できます。」	スキーマバージョン1では、再実行は主要な待ち時間の対象外です。	再実行は診断用として扱います。

ワークフロー

1. リポジトリの指示を確認します。正式な検証コマンドを特定します。
2. ワークフロー、イベント種別、ワークロード、検証契約、選択するジョブセットをそれぞれ1つずつ選びます。
3. 実行を記録する前に references/github.md を読みます。入力を作成する前に references/schemas.md を読みます。
4. ベースラインの初回試行と、選択した試行ごとのジョブページをすべて記録します。
5. 除外に備えた余裕を含む、計画上のサンプル数を記録します。ベースラインを正規化します。
6. 対象となる観測値と、除外された観測値を確認します。
7. CI とローカルの両方を比較する依頼では、ローカルの計測方法を定義する前に references/local.md を読みます。ローカル実行計画を定義し、正確なコマンド、ウォームアップとサンプルの回数、キャッシュ操作、分離方法、出力パス、費用を明記します。
8. CI とローカルの両方を比較する依頼では、ローカル実行計画について明示的な承認を得ます。
9. 具体的な変更計画を1つ提示します。
10. 影響を受けるファイル、期待される効果、リスク、検証方法、確立済みのロールバック手順があれば、それを明記します。
11. トラッキング対象のソース編集、ディスパッチ、リモート変更を行う前に、編集計画について明示的な承認を得ます。
12. 既存の実装および検証ワークフローに従って、承認済みの変更を適用します。
13. 同じ境界条件で CI の記録を完全に繰り返します。キュー待ち時間と起動遅延を含めます。
14. 変更後のデータセットを正規化します。明示した最小サンプル数を満たすデータセット同士を比較します。
15. 比較結果の JSON を読み込み、comparability: true を必須条件とします。
16. 必須チェック、カバレッジ、成果物、失敗時の動作を検証します。
17. 数値的な改善を約束せず、観測結果を報告します。報告後、または必要な入力が不足している時点で終了します。

CI のみを対象とする依頼では、ローカルの計測だけを省略します。ローカルの計測では、CI の待ち時間が改善したことを立証できません。キャッシュの対象群は分けて扱います。

承認の記録には、承認済みの環境、キャッシュ状態、またはローカルコマンドの差異を記載します。 ワークロード、検証、ID、または同等のカバレッジの不一致を免除することはできません。 因果関係を証明するものでも、編集を許可するものでもありません。

コマンド

実際に読み込まれた SKILL.md のディレクトリから CI_OPTIMIZE_HELPER の場所を特定します。 scripts/ci_optimize.py を使用する前に、シンボリックリンクを解決します。 コンシューマーリポジトリの現在のディレクトリからヘルパーのパスを導き出してはいけません。 このヘルパーは、コマンドの実行、ワークフローの編集、依存関係のインストール、実行のディスパッチ、変更のコミットを行いません。

コンシューマーリポジトリの作業ディレクトリからコマンドを実行します。

python3 "$CI_OPTIMIZE_HELPER" ci --input BEFORE-CAPTURES.json --output BEFORE.json
python3 "$CI_OPTIMIZE_HELPER" ci --input AFTER-CAPTURES.json --output AFTER.json
python3 "$CI_OPTIMIZE_HELPER" compare --before BEFORE.json --after AFTER.json --minimum-samples N --output COMPARISON.json

承認済みのキャッシュ対象群ごとに、異なる出力パスを指定して、この一連の操作を個別に実行します。 --force は、既存の明示的な出力ファイルを置き換える場合に限り使用します。 除外された実行によってジョブセットが変わらないことを確認するには、python3 "$CI_OPTIMIZE_HELPER" --self-test を実行します。

エビデンスとレポート

CI 指標の対象期間は、実行の作成から、選択したジョブの最新の完了までです。 主要コホートには初回試行のみを使用してください。並列ジョブの実行時間は合算しないでください。 ステータス、ワークフローと選択したジョブの境界、対象数と除外数、中央値と範囲、差分を報告してください。 チェック、成果物、制限事項、次の承認、エビデンスのパスを報告してください。 除外した観測値とその理由を残してください。 200 語以内で返してください。 無関係なゲートの名称を変更したり、自動修正チェックを追加したり、ローカルビルドの動作を変更したりしないでください。