nx-ci-monitor

CI モニターコマンド

Nx Cloud CI パイプラインの実行を監視し、自己修復による修正を処理するオーケストレーターです。ci-watcher サブエージェントを起動して CI のステータスをポーリングし、その結果に基づいて判断します。

コンテキスト

• 現在のブランチ: !git branch --show-current
• 現在のコミット: !git rev-parse --short HEAD
• リモートのステータス: !git status -sb | head -1

ユーザーの指示

$ARGUMENTS

重要: ユーザーから具体的な指示がある場合は、以下に記載されているデフォルトの動作よりも、その指示を優先してください。

デフォルト設定

設定	デフォルト	説明
--max-cycles	10	タイムアウトまでの CIPE サイクルの最大数
--timeout	120	最大時間（分）
--verbosity	medium	出力レベル：minimal、medium、verbose
--branch	(auto-detect)	監視するブランチ
--subagent-timeout	60	サブエージェントのポーリングタイムアウト（分）
--fresh	false	以前のコンテキストを無視して、新しく開始する
--auto-fix-workflow	false	CIPE 前の失敗に対する一般的な修正（例：ロックファイルの更新）を試す
--new-cipe-timeout	10	操作後に新しい CIPE が開始されるまで待つ時間（分）
--local-verify-attempts	3	CI にプッシュする前のローカル検証と改善サイクルの最大回数

$ARGUMENTS から上書き設定を解析し、デフォルトと統合してください。

Nx Cloud 接続の確認

重大: 監視ループを開始する前に、ワークスペースが Nx Cloud に接続されていることを確認してください。

ステップ 0：Nx Cloud 接続を確認する

1. ワークスペースのルートにある nx.json で nxCloudId または nxCloudAccessToken を確認します

2. nx.json がない、またはいずれのプロパティも存在しない場合 → 次を出力して終了します：

   [ci-monitor] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud
   

3. 接続されている場合 → メインループに進みます

セッションコンテキストの動作

重要: Claude Code セッション中は、会話のコンテキストが保持されます。モニターを中断するために Ctrl+C を押してから /ci-monitor を再実行すると、Claude は以前の状態を記憶しており、その時点から続行することがあります。

• 監視を続行する場合： /ci-monitor を再実行してください（コンテキストは保持されます）
• 新しく開始する場合： /ci-monitor --fresh を使って、以前のコンテキストを無視してください
• 完全に初期化する場合： Claude Code を終了し、claude を再起動してください

ステータス別のデフォルト動作

サブエージェントは、次のいずれかのステータスで戻ります。この表では、各ステータスのデフォルト動作を定義します。ユーザーの指示は、これらの動作を上書きできます。

ステータス	デフォルト動作
ci_success	成功として終了します。「CI passed successfully!」とログに記録します。
fix_auto_applying	修正はセルフヒーリングによって自動適用されます。MCP は呼び出さないでください。last_cipe_url を記録し、新しい CIPE をポーリングするため、待機モードで新しいサブエージェントを起動します。
fix_available	failedTaskIds と verifiedTaskIds を比較して、検証状態を判断します。以下の修正可能時の判断ロジックのセクションを参照してください。
fix_failed	セルフヒーリングによる修正の生成に失敗しました。taskOutputSummary に基づいてローカルで修正を試みます。成功した場合は → コミット、プッシュしてループします。失敗した場合は → 失敗として終了します。
environment_issue	再実行をリクエストするため、MCP を呼び出します：update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })。新しい CIPE が自動的に起動します。新しい CIPE をポーリングするループに進みます。
no_fix	CI が失敗し、修正を利用できません（セルフヒーリングが無効、または実行できません）。可能であればローカルで修正を試みます。それ以外の場合は、失敗として終了します。
no_new_cipe	期待された CIPE が起動しませんでした（Nx タスクより前に CI ワークフローが失敗した可能性があります）。ユーザーに報告し、設定されていれば一般的な修正を試みるか、手順を案内して終了します。
polling_timeout	サブエージェントのポーリングがタイムアウトに達しました。タイムアウトとして終了します。
cipe_canceled	CIPE がキャンセルされました。キャンセル済みステータスで終了します。
cipe_timed_out	CIPE がタイムアウトしました。タイムアウトステータスで終了します。
error	no_progress_count を増やします。3 以上の場合 → サーキットブレーカーで終了します。それ以外の場合は、60 秒待機してループします。

修正可能時の判断ロジック

サブエージェントが fix_available を返した場合、メインエージェントは failedTaskIds と verifiedTaskIds を比較します。

ステップ 1：タスクを分類する

1. 検証済みタスク = failedTaskIds と verifiedTaskIds の両方に含まれるタスク
2. 未検証タスク = failedTaskIds に含まれ、verifiedTaskIds には含まれないタスク
3. E2E タスク = 未検証タスクのうち、ターゲットに「e2e」を含むもの（タスク形式：<project>:<target> または <project>:<target>:<config>）
4. 検証可能なタスク = e2e ではない未検証タスク

ステップ 2：進む経路を決定する

条件	経路
未検証タスクがない（すべて検証済み）	MCP 経由で適用
未検証タスクがあるが、すべて e2e である	MCP 経由で適用（十分に検証済みとして扱う）
検証可能なタスクがある	ローカル検証フロー

ステップ 3a：MCP 経由で適用する（すべて検証済み／e2e のみ検証済み）

• update_self_healing_fix({ shortLink, action: "APPLY" }) を呼び出します
• last_cipe_url を記録し、待機モードでサブエージェントを起動します

ステップ 3b：ローカル検証フロー

検証可能なタスク（E2E 以外）で、まだ検証されていないものがある場合：

1. パッケージマネージャーを検出します：

   • pnpm-lock.yaml が存在する場合 → pnpm nx
   • yarn.lock が存在する場合 → yarn nx
   • それ以外の場合 → npx nx

2. 検証可能なタスクを並列実行します：

   • general サブエージェントを起動し、各タスクを同時に実行します
   • 各サブエージェントが実行するコマンド：<pm> nx run <taskId>
   • すべてのサブエージェントから成功／失敗の結果を収集します

3. 結果を評価します：

結果	アクション
検証可能なタスクがすべて成功	MCP 経由で適用
検証可能なタスクが 1 つでも失敗	ローカルで適用して拡張するフロー

1. ローカルで適用して拡張するフロー：

   • nx apply-locally <shortLink> を実行します
   • 失敗したタスクを修正するため、コードを拡張します
   • 失敗したタスクを再実行して修正を検証します
   • それでも失敗する場合 → local_verify_count を増やし、拡張の手順に戻ります
   • 成功した場合 → コミットしてプッシュし、expected_commit_sha を記録して、待機モードでサブエージェントを起動します

2. 試行回数を追跡します（ステップ 4 をラップします）：

   • 各拡張サイクルの後に local_verify_count を増やします
   • local_verify_count >= local_verify_attempts（デフォルト：3）の場合：

     • コードをコミット可能な状態にします

     • ローカル検証が失敗したことを示すメッセージでコミットしてプッシュします

     • ユーザーに報告します：

       [ci-monitor] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds>
       

     • expected_commit_sha を記録し、待機モードでサブエージェントを起動します（CI を最終判定とします）

コミットメッセージの形式

git commit -m "fix(<projects>): <brief description>

Failed tasks: <taskId1>, <taskId2>
Local verification: passed|enhanced|failed-pushing-to-ci"

未検証の修正フロー（検証を試みていない場合）

verificationStatus が FAILED または NOT_EXECUTABLE の場合、あるいは検証されていない修正で couldAutoApplyTasks != true の場合：

• 修正内容（suggestedFix、suggestedFixReasoning、taskOutputSummary）を分析します
• 修正が正しいと思われる場合 → MCP 経由で適用します
• 修正に拡張が必要な場合 → 上記の「ローカルで適用して拡張するフロー」を使用します
• 修正が誤っている場合 → MCP 経由で却下し、一から修正してコミットし、プッシュします

自動適用の条件

couldAutoApplyTasks フィールドは、修正が自動適用の対象かどうかを示します：

• true：修正は自動適用の対象です。検証中、サブエージェントはポーリングを続けます。検証に成功すると fix_auto_applying を返し、失敗すると fix_available を返します。
• false または null：修正には手動操作が必要です（MCP 経由で適用、ローカルで適用、または却下）

重要な点：サブエージェントが fix_auto_applying を返した場合、適用のために MCP を呼び出してはいけません。自己修復で処理されます。待機モードで新しいサブエージェントを起動してください。

適用、却下、ローカルでの適用

• MCP 経由で適用：update_self_healing_fix({ shortLink, action: "APPLY" }) を呼び出します。自己修復エージェントが CI で修正を適用し、新しい CIPE が自動的に起動します。ローカルでの git 操作は不要です。
• ローカルで適用：nx apply-locally <shortLink> を実行します。パッチをローカルの作業ディレクトリに適用し、状態を APPLIED_LOCALLY に設定します。プッシュ前に修正を拡張したい場合に使用します。
• MCP 経由で却下：update_self_healing_fix({ shortLink, action: "REJECT" }) を呼び出します。修正を却下済みとしてマークします。修正が完全に誤っていて、一から修正する場合にのみ使用してください。

ローカルでの適用と拡張のフロー

修正に拡張が必要な場合（却下せず、nx apply-locally を使用します）：

1. パッチをローカルに適用します：nx apply-locally <shortLink>（これにより状態も APPLIED_LOCALLY に更新されます）

2. 必要に応じて追加の変更を行います

3. コミットしてプッシュします：

   git add -A
   git commit -m "fix: resolve <failedTaskIds>"
   git push origin $(git branch --show-current)
   

4. 新しい CIPE をポーリングするループに戻ります

却下して一から修正するフロー

修正が完全に誤っている場合：

1. MCP を呼び出して却下します：update_self_healing_fix({ shortLink, action: "REJECT" })

2. ローカルで問題を一から修正します

3. コミットしてプッシュします：

   git add -A
   git commit -m "fix: resolve <failedTaskIds>"
   git push origin $(git branch --show-current)
   

4. 新しい CIPE をポーリングするループに戻ります

環境問題への対処

failureClassification == 'ENVIRONMENT_STATE' の場合：

1. MCP を呼び出して再実行を要求します：update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })
2. 新しい CIPE が自動的に起動します（ローカルでの Git 操作は不要です）
3. previousCipeUrl を設定して、新しい CIPE のポーリングを繰り返します

新しい CIPE がない場合の対処

status == 'no_new_cipe' の場合：

これは、想定されていた CIPE が作成されなかったことを意味します。CI が Nx タスクの実行前に失敗した可能性があります。

1. ユーザーに報告します：

   [ci-monitor] No CI attempt for <sha> after 10 min. Check CI provider for pre-Nx failures (install, checkout, auth). Last CI attempt: <previousCipeUrl>
   

2. ユーザーが自動修正の試行を設定している場合（例：--auto-fix-workflow）：

   • パッケージマネージャーを検出します：pnpm-lock.yaml、yarn.lock、package-lock.json を確認します

   • インストールを実行してロックファイルを更新します：

     pnpm install   # or npm install / yarn install
     

   • ロックファイルに変更があった場合：

     git add pnpm-lock.yaml  # or appropriate lockfile
     git commit -m "chore: update lockfile"
     git push origin $(git branch --show-current)
     

   • 新しいコミット SHA を記録し、expectedCommitSha を指定してポーリングを繰り返します

3. それ以外の場合： no_new_cipe ステータスで終了し、ユーザーが調査するための手順を提示します

終了条件

以下のいずれかの条件が満たされた場合、監視ループを終了します：

条件	終了タイプ
CI が成功する（cipeStatus == 'SUCCEEDED'）	成功
CIPE の最大サイクル数に達する	タイムアウト
最大実行時間に達する	タイムアウト
進展のない反復が 3 回連続する	サーキットブレーカー
修正方法がなく、ローカルでの修正も不可能	失敗
新しい CIPE がなく、自動修正も設定されていない	CIPE 起動前の失敗
ユーザーがキャンセルする	キャンセル

メインループ

ステップ 1：追跡を初期化する

cycle_count = 0
start_time = now()
no_progress_count = 0
local_verify_count = 0
last_state = null
last_cipe_url = null
expected_commit_sha = null

ステップ 2：サブエージェントを起動する

CI ステータスをポーリングするために、ci-watcher サブエージェントを起動します：

新規開始（初回起動、想定される CIPE がない場合）：

Task(
  agent: "ci-watcher",
  prompt: "Monitor CI for branch '<branch>'.
           Subagent timeout: <subagent-timeout> minutes.
           New-CIPE timeout: <new-cipe-timeout> minutes.
           Verbosity: <verbosity>."
)

新しい CIPE を起動するアクションの後（待機モード）：

Task(
  agent: "ci-watcher",
  prompt: "Monitor CI for branch '<branch>'.
           Subagent timeout: <subagent-timeout> minutes.
           New-CIPE timeout: <new-cipe-timeout> minutes.
           Verbosity: <verbosity>.

           WAIT MODE: A new CIPE should spawn. Ignore old CIPE until new one appears.
           Expected commit SHA: <expected_commit_sha>
           Previous CIPE URL: <last_cipe_url>"
)

ステップ 3：サブエージェントの応答を処理する

サブエージェントから応答が返されたら：

1. 返されたステータスを確認します
2. 上記の表でデフォルトの動作を確認します
3. ユーザーの指示がデフォルトの動作を上書きするか確認します
4. 適切なアクションを実行します
5. アクションによって新しい CIPE が作成される場合、追跡情報を更新します（ステップ 3a を参照）
6. アクションによってループが続く場合は、ステップ 2 に進みます

ステップ 3a：新しい CIPE の検出に向けた状態の追跡

新しい CIPE のトリガーとなるアクションの後、ループに戻る前に状態を記録します。

アクション	追跡する内容	サブエージェントモード
自動適用の修正	last_cipe_url = current cipeUrl	待機モード
MCP 経由で適用	last_cipe_url = current cipeUrl	待機モード
ローカルで適用してプッシュ	expected_commit_sha = $(git rev-parse HEAD)	待機モード
拒否して修正し、プッシュ	expected_commit_sha = $(git rev-parse HEAD)	待機モード
修正に失敗し、ローカルで修正してプッシュ	expected_commit_sha = $(git rev-parse HEAD)	待機モード
修正せず、ローカルで修正してプッシュ	expected_commit_sha = $(git rev-parse HEAD)	待機モード
環境を再実行	last_cipe_url = current cipeUrl	待機モード
新しい CIPE がなく、自動修正してプッシュ	expected_commit_sha = $(git rev-parse HEAD)	待機モード

重要：サブエージェントに expectedCommitSha または last_cipe_url を渡すと、サブエージェントは待機モードになります。

• サブエージェントは古い／期限切れの CIPE を完全に無視します。
• サブエージェントは新しい CIPE が現れるまで待機します。
• サブエージェントが古い CIPE のデータを持ってメインエージェントに戻ることはありません。
• 新しい CIPE が検出されると、サブエージェントは通常のポーリングに切り替わります。

コンテキストの保持に待機モードが重要な理由：古い CIPE のデータは非常に大きくなる場合があります（タスク出力の要約、提案された修正パッチ、推論など）。サブエージェントがこれをメインエージェントに返すと、その CIPE の処理はすでに完了しているため、不要なデータでメインエージェントのコンテキストが埋まってしまいます。待機モードでは古いデータをサブエージェント内に保持し、メインエージェントには送信しません。

ステップ 4：進捗の追跡

各アクションの後：

• 状態が大きく変化した場合 → no_progress_count = 0 にリセットします
• 状態に変化がない場合 → no_progress_count++
• 新しい CI の試行が検出された場合 → local_verify_count = 0 にリセットします

ステータス報告

詳細レベルに応じて報告します。

レベル	報告内容
minimal	最終結果（成功／失敗／タイムアウト）のみ
medium	状態の変化と定期的な更新（「サイクル N | 経過時間：Xm | ステータス：...」）
verbose	medium のすべてに加えて、サブエージェントからの全応答、Git の出力、MCP の応答

ユーザー指示の例

ユーザーはデフォルトの動作を上書きできます。

指示	効果
「自動適用は絶対にしないで」	修正を適用する前に必ず確認します
「Git のプッシュ前に必ず確認して」	プッシュのたびに確認します
「e2e タスクの修正はすべて拒否して」	failedTaskIds に e2e が含まれる場合は自動的に拒否します
「検証結果に関係なく、すべての修正を適用して」	検証チェックを省略し、すべてを適用します
「信頼度が 70 未満なら拒否して」	適用前に信頼度フィールドを確認します
「適用前に 'nx affected -t typecheck' を実行して」	ローカル検証の手順を追加します
「ワークフローの失敗を自動修正して」	CIPE 前の失敗に対してロックファイルの更新を試みます
「新しい CIPE を 45 分待って」	新しい CIPE のタイムアウトを上書きします（デフォルト：10 分）

エラー処理

エラー	対応
Git のリベース競合	ユーザーに報告して終了します
nx apply-locally が失敗	ユーザーに報告し、手動でパッチを適用するか終了します
MCP ツールのエラー	1 回再試行し、失敗した場合はユーザーに報告します
サブエージェントの起動失敗	1 回再試行し、失敗した場合はエラーで終了します
新しい CIPE が検出されない	--auto-fix-workflow が指定されている場合はロックファイルの更新を試み、それ以外の場合はガイダンスを添えてユーザーに報告します
ロックファイルの自動修正に失敗	ユーザーに報告し、CI ログを確認するよう案内して終了します

セッション例

例 1：自己修復を伴う通常のフロー（中程度の詳細さ）

[ci-monitor] Starting CI monitor for branch 'feature/add-auth'
[ci-monitor] Config: max-cycles=5, timeout=120m, verbosity=medium

[ci-monitor] Spawning subagent to poll CI status...
[CI Monitor] CI attempt: IN_PROGRESS | Self-Healing: NOT_STARTED | Elapsed: 1m
[CI Monitor] CI attempt: FAILED | Self-Healing: IN_PROGRESS | Elapsed: 3m
[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 5m

[ci-monitor] Fix available! Verification: COMPLETED
[ci-monitor] Applying fix via MCP...
[ci-monitor] Fix applied in CI. Waiting for new CI attempt...

[ci-monitor] Spawning subagent to poll CI status...
[CI Monitor] New CI attempt detected!
[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 8m

[ci-monitor] CI passed successfully!

[ci-monitor] Summary:
  - Total cycles: 2
  - Total time: 12m 34s
  - Fixes applied: 1
  - Result: SUCCESS

例 2：CI 前の失敗（中程度の詳細さ）

[ci-monitor] Starting CI monitor for branch 'feature/add-products'
[ci-monitor] Config: max-cycles=5, timeout=120m, auto-fix-workflow=true

[ci-monitor] Spawning subagent to poll CI status...
[CI Monitor] CI attempt: FAILED | Self-Healing: COMPLETED | Elapsed: 2m

[ci-monitor] Applying fix locally, enhancing, and pushing...
[ci-monitor] Committed: abc1234

[ci-monitor] Spawning subagent to poll CI status...
[CI Monitor] Waiting for new CI attempt... (expected SHA: abc1234)
[CI Monitor] ⚠️  CI attempt timeout (10 min). Returning no_new_cipe.

[ci-monitor] Status: no_new_cipe
[ci-monitor] --auto-fix-workflow enabled. Attempting lockfile update...
[ci-monitor] Lockfile updated. Committed: def5678

[ci-monitor] Spawning subagent to poll CI status...
[CI Monitor] New CI attempt detected!
[CI Monitor] CI attempt: SUCCEEDED | Elapsed: 18m

[ci-monitor] CI passed successfully!

[ci-monitor] Summary:
  - Total cycles: 3
  - Total time: 22m 15s
  - Fixes applied: 1 (self-healing) + 1 (lockfile)
  - Result: SUCCESS