ci-integration

CI 統合

価値: フィードバック — CI パイプラインはシグナルを生成します。規律ある操作パターンによって、シグナルが適切に受信、分類され、正しく対処されるようにします。規律のない CI 操作（失敗中の実行を無視して再度プッシュする、フレーキーテストを無視するなど）は、パイプラインのシグナルを劣化させ、ノイズに変えてしまいます。

目的

規律ある CI/CD の操作方法を学びます。保留中の実行は一度に 1 つだけにすること、失敗を構造的にトリアージすること、機械的な失敗を自動修復すること、パイプラインで利用できる構造化された証跡を出力することを扱います。最も一般的な CI の失敗パターン、つまり前回の実行が失敗した理由を理解する前に再度プッシュすることを防ぎます。

プラクティス

プッシュ後は完了まで待機

保留中の CI 実行は一度に 1 つだけにします。実行中にプッシュしてはいけません。

1. コミットをプッシュします
2. CI 実行が完了するまでポーリングするか、待機します
3. 何らかの対応を取る前に、結果の全体を確認します
4. 実行が完了した後（成功でも失敗でも）に限り、再度プッシュできます

推奨事項:

• プッシュが必要となる新しい作業を始める前に、CI の完了を待ちます
• ステータスバッジだけでなく、CI の出力全体を確認します

禁止事項:

• 前の実行がまだ保留中の間に、「修正」をプッシュします
• 実行が成功すると決めつけて、後続のコミットをプッシュします
• 新しい実行をプッシュするために、実行をキャンセルします（実行が明らかに古くなっている場合を除く）

失敗のトリアージ

修正を試みる前に、CI の失敗をすべて分類します。分類によって修正方針が決まります。

分類	シグナル	修正方針
test-failure	テストのアサーションが失敗	debugging-protocol に引き継ぎます
lint-failure	リンターまたはフォーマッターのエラー	自動修正：フォーマッターを実行し、コミットして再度プッシュします
build-failure	コンパイルまたは依存関係のエラー	依存関係を分析し、ロックファイルを確認します
flaky-test	コード変更なしで、再試行するとテストが成功する	フラグを付けて追跡します（以下を参照）
infra-failure	ネットワーク、ランナー、またはサービスのエラー	再試行します（最大 2 回）。その後、エスカレーションします

分類するには、CI ログ全体を確認します。ステータスだけから推測してはいけません。

自動修復

決定的な修正方法がある機械的な失敗は、自動的に解決します。

1. Lint／フォーマットの失敗： プロジェクトのフォーマッターまたはリンターを自動修正付きで実行し、結果をコミットして再度プッシュします。再試行は 1 回だけです。フォーマッターで問題を解決できない場合は、build-failure に分類します。
2. インフラの失敗： CI の実行を再試行します（最大 2 回）。すべての再試行が失敗した場合は、インフラエラーの詳細を添えてユーザーにエスカレーションします。
3. テストの失敗： 自動で再試行してはいけません。調査のために debugging-protocol に引き継ぎます。テストの失敗はノイズではなく、シグナルです。
4. ビルドの失敗： 依存関係のロックファイル、ビルド設定、環境の差異を確認します。考えずに再試行してはいけません。

フレーキーテストの検出

コード変更なしで再試行すると成功する場合、そのテストはフレーキーです。

検出した場合：

1. テスト名、ファイル、フレーキーな実行での失敗出力を記録して、テストにフラグを付けます
2. プロジェクトのメモリに記録します（factory モードが有効な場合は .factory/audit-trail/flaky-tests.json、それ以外の場合はプロジェクトのメモ）
3. ユーザーに報告します。フレーキーテストは CI への信頼を損なうため、対処が必要です
4. フレーキーテストが解消されるまで、品質ゲートの目的上、フレーキーな成功を本当の成功として扱ってはいけません

構造化出力

CI のやり取りでは毎回、CI_RESULT 証跡パケットを生成します。

{
  "run_id": "string (CI run identifier)",
  "status": "string (passed | failed | cancelled)",
  "duration": "number (seconds)",
  "failure_type": "string (test-failure | lint-failure | build-failure | flaky-test | infra-failure) -- omit if passed",
  "failure_details": "string (summary of failure) -- omit if passed",
  "fixes_applied": ["string (description of each auto-fix applied)"],
  "retry_count": "number (0 if no retries)"
}

このパケットは、パイプラインオーケストレーターと監査証跡で使用されます。実行が成功した場合でも、必ず生成してください。

適用に関する注記

• パイプラインモード：ゲート方式です。CI の成功／失敗によってマージを機械的に制御します。
• スタンドアロンモード：推奨方式です。エージェントがプッシュ後の待機規律を自ら適用します。

厳守事項：

• プッシュ後は完了まで待機：パイプラインモードでは [H]、スタンドアロンでは [RP]
• フレーキーな成功を本当の成功として数えないこと：[H]

制約

• プッシュして待機：保留中の実行は常に 1 件です。「ブランチごとに 1 件」でも「変更の種類ごとに 1 件」でもありません。CI の実行中は、変更がどれほど無関係に見えてもプッシュしないでください。CI リソースの競合とマージ順序が重要であるため、この規律を守ります。
• 失敗の分類：修正を試みる前に分類してください。「修正を試してうまくいったから、リンターの失敗に違いない」ということではありません。修正方針を決めるのは分類であり、その逆ではありません。自信を持って分類できない場合は、推測して修正せず、さらに調査してください。
• 不安定なテスト：不安定なテストとは、同じコードで異なる結果を出すテストです。「コードを変更せずに再試行すると成功する」ことが定義です。環境を変更した場合、その再試行は不安定さの証拠ではなく、環境依存のテストである証拠です。これらは異なる問題であり、修正方法も異なります。

検証

CI とやり取りするたびに、以下を確認してください。

• プッシュする前に、前回の CI 実行が完了するまで待機した
• CI の出力全体を読んだ（ステータスだけではない）
• 修正を試みる前に失敗の種類を分類した
• 分類に応じた適切な修正方針を適用した
• テストの失敗を再試行せず、デバッグプロトコルに回した
• リント／フォーマットの自動修正は 1 回に限定した
• インフラの再試行は 2 回を超えなかった
• 不安定なテストにフラグを付け、記録した
• CI_RESULT エビデンスパケットを作成した

いずれかの基準を満たしていない場合は、先に進む前に該当するプラクティスを見直してください。

依存関係

このスキルは、CI/CD パイプラインを備えたあらゆるプロジェクトで単独で機能します。以下と連携します。

• debugging-protocol：テストの失敗は、やみくもに修正を試みるのではなく、体系的な調査のためにデバッグプロトコルに回されます
• tdd：TDD サイクル中の CI の失敗は RED-GREEN ループにフィードバックされます。CI でのテスト失敗は、サイクルが完了していないことを意味します
• pipeline：ファクトリーモード内で使用する場合、パイプラインオーケストレーターは CI_RESULT パケットを使用して品質ゲートを評価します

依存関係が不足していますか？次のコマンドでインストールしてください。

npx skills add jwilger/agent-skills --skill debugging-protocol