# 夜間ジョブ異常を通知で終わらせず、自動修復→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（等）に修理を依頼する。 隔離した 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コーダー起動・通知送信）が 一切発生しないことを確認してから、本番実行に切り替える。 ---