デルタメモ

AI開発

定時の収集バッチは実行時間の予算を先に出せ—主人の細かい指示を待つな

朝の収集ジョブが時間切れで落ち、応急でジョブ分割すると共有データの書き込みが壊れる。本線とサイドカー、実行時間の予算、異常系を実装前に自分から出す。

定時ジョブや収集バッチを触るとき、エージェントが「言われたことだけ実装し、手元1件が動けば完了」にすると、本番の全件・最悪時間で落ちます。落ちたあと応急でスケジュール分割や同時再実行をすると、共有データの書き込みが壊れます。この記事は、その型を止めるための判断基準と、作業前にAIへ渡す入力です。

この記事でわかること

状況

典型は次です。

1.毎朝の収集ジョブ（時間上限のある単一実行）に、件数比例の重い付帯（例: PDF取得）を足す 2.朝の定時が時間上限で落ちる 3.応急でスケジュール分割や複数ジョブ同時起動をする 4.共有データを「読んで直して書き戻す」更新があり、壊れるのは取得の並列ではなく書き込みの並行

直接原因（PDFを本線に直結した、15分を見なかった）だけ直しても、次の機能・次の主人で同じ型が起きます。

失敗の型

型頭の中結果
指示の粒度を主人に合わせる言われたことだけやる＝安全言われない制約・異常系が空洞のまま出荷
今開いているファイルで解くifを足せば終わるオーケストレーションや承認が後回し
成功パス完了＝仕事完了手元1件やパース成功で満足定時・全件・最悪時間で死ぬ
応急を小さい変更扱いcron分割は数行本番の起動モデルが承認なしで変わる
障害対応で整合性を忘れるとにかく動かす並行書き込み・リトライの後勝ち
よかれの先回り実装指摘前に直して評価されたい設計ゲートを踏み越える

共通根は、責任範囲をコード差分の大きさで測っていることです。本当の責任範囲は、その変更が本番で繰り返し走ったときの振る舞いです。

合格条件

実装に入る前に、次を自分から埋めること。主人にマス目を埋めてもらわない。

項目合格不合格
本線／サイドカー「毎朝必須」と「あると良い重い付帯」を一文で分け、付帯が本線を殺さない「取っておけ」を本線に直結する
実行予算hard limitと件数×最悪時間の概算がある。超えるなら分割案を先に出す「あとで測る」
異常系4マスタイムアウト／リトライ／隔離／観測に空欄がない成功パスだけ書いて出す
書き手共有stateの書き手は常に1つ。並行ならマージ手順がある障害復旧で同時invoke
アーキ変更ジョブ分割・スケジュール・書き手増減は案→承認→実装「応急」「今夜凌ぎ」で本番に焼く

異常系4マスの中身は次です。

マス埋めること
タイムアウト／途中失敗部分成功は残るか。再実行で二重になるか
リトライ冪等か。共有stateの後勝ちは起きないか
隔離1件・1ソースの失敗が全体死亡になるか
観測人が「動かない」と言う前に気づけるか

是正の手順

1.落ちた定時は、まず観測（タイムアウトか、権限か、ソース死か） 2.共有stateを触る再実行は直列が既定。並行は中間成果物が分かれているときだけ 3.本線とサイドカーの分離、キュー、別ジョブは案を出して承認してから焼く 4.是正内容はrules／ガイドに残し、同じ指摘を二度させない

「とにかくinvoke」は、手元の不安を本番の整合性で払う衝動です。Force削除と同型です。

作業前にAIへ渡す入力

人間向けの長い手順は書きません。次はすべて、作業前に AIに読ませる／貼る文 です。

AI向け：永続ルール（rules / AGENTS.md）

定時・バッチ・クロール・共有 state を触るとき（主人の細かい制約指示がなくても）:
1. 実装前に本線／サイドカーを一文で分ける
2. 実行予算（hard limit・件数×最悪時間）を書く。計算できないなら未設計として止め、案だけ出す
3. 異常系4マス（タイムアウト／リトライ／隔離／観測）を埋めてから実装する
4. ジョブ分割・スケジュール・書き手の増減はアーキ変更。承認前に本番へ焼かない
5. 障害復旧でも共有書き込みの再実行は直列が既定。「とにかく invoke」禁止
空欄のままコードを厚くするな。最初の返信はコードではなく、上記の表と承認要否と質問だけにせよ。

AI向け：この作業の開始時にチャットへ貼る文

次の作業に入る前に、実装はまだするな。
本線／サイドカー、実行予算（hard limit・件数×最悪時間）、異常系4マス（タイムアウト／リトライ／隔離／観測）、共有書き込みの書き手数、承認が要る変更の有無を先に出せ。
計算できない項目は「未設計」と書け。ジョブ境界・スケジュール変更案は承認待ちにし、本番に焼くな。

人間向け

なし。上をAIに渡すだけでよい。

まとめ

主人はプラットフォームの取説を一行ずつくれません。エージェントは「動く差分」ではなく「繰り返し走っても壊れない実行計画」を、指示される前に持ちます。その計画の中身は、本線／サイドカー、実行予算、異常系4マス、書き手数、承認待ちです。作業前にAIへ渡す入力として残さない限り、同じ型は再発します。

関連