夜間ジョブ異常を通知で終わらせず、自動修復→AI修理PR→人へ引き渡す閉ループ

背景

夜間バッチ・定時同期・監視ジョブの異常検知は、たいてい「検知して通知」で止まる。 異常が起きるたびに<通知先>へDMが飛び、それを読んだ人が毎回手で原因を調べて直す。 検知の精度を上げても、この「読む→調べる→直す」という人手の工程自体は減らない。 むしろ検知が賢くなるほど通知の頻度が増え、読む手間だけが積み上がる。

この指示書は、検知の後段に「決定的な自動修復」「AIコーダーによる修理PR」「人には 本当に判断が要るものだけ渡す」という3段の閉ループを足す設計を示す。

全体の流れ

1. 検知ツールは、通知するかどうかに関係なく、異常を毎回1件1オブジェクトのJSONとして <異常キャッシュ> に書き出す。通知は「読む用」、JSONは「機械が次に処理する用」と役割を分ける。
2. 検知の直後に remediate ツールが起動し、<異常キャッシュ> を読んで1件ずつ処理する。
3. まず決定的 Playbook 群にかける。Playbook は match(異常) -> bool、 apply(異常) -> 結果、verify(異常) -> bool の3関数を持つ小さな1ファイル1モジュールにする。 例:
   • 初回未実行（過去に一度も成功実績がない）ジョブの失敗は誤検知として除外する
   • 直後の再実行が成功していれば「自然回復」として片付ける
   • 429/5xxの直後にfailover先が成功していれば除外する
   • 実行中(Running)のまま規定時間を超えたタスクは停止させる
   • staleなタスクは当日の時間帯内で1回だけ再実行し、成果物の有無で検証する
   • ログ追記時のEBUSYは、呼び出し元にリトライ実装があるかどうかで「様子見」か「異常」かを分ける
4. どのPlaybookにも一致しない異常は、AIコーダーCLI（<AIコーダーCLI>等）に修理を依頼する。 隔離した git worktree を1つ切り、その中で作業させる。 渡す情報は「異常の内容」「ログ末尾（秘匿マスク済み）」「疑わしいファイル」 「要求: 最小差分で直す・回帰テストを追加する・全テストを緑にする・pushはしない」の4点。 これらは必ずファイルに書き出してAIコーダーCLIに渡す（後述の落とし穴を参照）。 AIコーダーの作業後、remediate側でテストを実走し、緑ならpushして automerge ラベル付きのPRを作る。
5. 次の上限のいずれかに触れた異常は、その回は処理せず「持ち越し(deferred)」として 次回のremediate実行に回す。人には渡さない。
   • 1回のremediate実行で処理する件数は3件まで
   • 1回の処理時間は45分まで
   • 同一fingerprint（異常の種類+対象の組み合わせ）は3日以内は再試行しない
   • 対象について既にPRがopen中なら再実行しない
6. AIコーダーのレーンでも直らなかった異常（テストが緑にならない、差分が妥当でない等）だけを 人に渡す。渡す形式は次の3要素に固定する。
   • 何が起きたか（異常の内容と発生時刻）
   • 何を試したか（どのPlaybookを試して不一致だったか、AIコーダーが何を変更しようとして 何のテストが落ちたか）
   • 判断してほしい1点（人が決めるべき論点を1つに絞る。複数ある場合は最重要の1つだけ出し、 残りはPR内のコメントに書く）
7. 通知はremediateの1回の実行につき最大1通にまとめる。異常が0件の回は通知しない。 同一内容（同じfingerprint）の通知は24時間は再送しない。処理履歴は <台帳>（jsonl、1行1イベント）に追記していく。

落とし穴（実測ベース）

• AIコーダーCLIへの指示をargv（コマンドライン引数）で渡すと、シェルが バッククォートをコマンド置換として実行してしまう。 指示文中にファイル名やコード片を バッククォートで書いただけで、意図しないコマンドが実行され、渡したはずの指示内容が 消えたり別の出力に置き換わったりする。指示は必ず一時ファイルに書いてから 「そのファイルを読んで実行して」という形でCLIに渡す。シェルを1段でも経由すると "$(cat file)"のような「理屈上は安全」な書き方でも展開されることがあるため、 ファイル渡しを徹底する。
• AIコーダーCLIの出力を| tailのようにパイプすると、バッファリングされて 「実行中」なのか「止まっている(hang)」なのか区別がつかなくなる。ログはファイルに 書かせて別途tailするか、タイムアウト付きで待ち受ける。
• スケジュールタスクが1件も無い環境や、異常キャッシュが空の実行で全体が 例外落ちしないよう、異常1件ごとにtry-catchで囲み、1件の失敗が他の件の処理を 止めないようにする。
• 秘匿マスクをwebhook URLだけに適用するのは不十分。APIキー・アクセストークン・ 秘密鍵らしき文字列パターンまで検出してマスクしないと、ログ経由でAIコーダーや 通知先に秘密情報が渡ってしまう。
• テスト実行にtimeoutを付けないと、テストがハングした時に検知ツール自体が 止まり、後続の検知・remediateサイクルも動かなくなる。
• レート制限のうち「日次上限」由来の429は、待ってリトライしても当日中は 回復しない。リトライループに入れず、即座にそのジョブをクールダウン状態にする。
• ログを「失敗した時しか書かない」設計のジョブは、staleの誤検知源になりやすい。 正常終了時にも短いハートビート行を書かせることで、「ログが無い=動いていない」を 正しく判定できるようにする。
• 「上限に達したので人に回す」は禁止パターン。件数・時間・再試行間隔の上限に 触れたものは必ず持ち越し(deferred)にし、人への引き渡しは「AIレーンでも 直らなかったもの」だけに絞る。

検証の型

remediateツールに--dry-runオプションを持たせ、各異常について 「playbook名」「codex（AIコーダーレーンに回す）」「deferred(理由)」「escalate(理由)」 のいずれかを表すPLAN行だけを出力させる。実際に溜まっている異常キャッシュに対して --dry-runを実行し、副作用（Playbookのapply実行・AIコーダー起動・通知送信）が 一切発生しないことを確認してから、本番実行に切り替える。