「翌朝のバッチ結果で判定する」ゲートを、朝を待たずに閉じる

この指示書が解く問題

夜間バッチ（毎朝 07:00 にレポートを吐くジョブなど）に変更を入れたあと、 「効いたかどうかは明朝のレポートで確認する」という宿題の残し方をすることがある。

これをそのまま運用すると、次の2つが同時に起きる。

1. 判定が1日1回しか進まない。 夕方に実装を終えても、確認は翌朝まで待ち。 翌朝の担当が別の作業をしていれば、さらに1日延びる。
2. 待ったのに判定できない。 朝より前にセッションが始まると「まだ時刻が来ていません」で終わる。 実際、これで2セッション連続で判定できずに終わった例がある。

しかし多くの場合、待つ必要はない。判定の対象は時刻ではなく、コードが吐く出力だからだ。 同じコード・同じ入力を再現できれば、いつでも判定できる。

手順

1. その判定が何に依存しているかを分ける

ゲートの完了条件を読み、次のどちらかに仕分ける。

• 出力依存（前倒しできる）: 「レポートに3つの節が出ているか」「禁止語が0件か」「前日比が付いているか」
• 時刻依存（前倒しできない）: 「07:00 にジョブが起動したか」「タスクスケジューラの LastTaskResult が 0 か」

出力依存の条件は、バッチ本体を手で走らせれば今すぐ判定できる。 時刻依存の条件だけを翌朝に残す。この仕分けをしないと、全部を翌朝に送ってしまう。

2. 副作用を止めるフラグと、出力先を差し替えるフラグを探す

バッチにこの2つがあるかを確認する。無ければ足すのが先（これ自体が価値のある改修）。

<バッチ> --dry        # 通知（Slack / Discord / メール）を送らない。ファイルには書く
<バッチ> --out-root <一時ディレクトリ>   # 成果物の書き込み先を丸ごと差し替える

重要なのは --no-scan のような「重い処理を省く」フラグは付けないこと。 省いた部分こそが検証したい節であることが多く、付けると空の節が出て判定できない。 時間がかかっても実経路を通す。

3. 🔴 前日データを一時ディレクトリへシードする（ここが罠）

「前日比」「前回との差分」を出す節は、たいてい出力先ディレクトリから前日のファイルを読む。

readPreviousDay(date) {
  return JSON.parse(fs.readFileSync(
    path.join(OUT_ROOT, 'analysis', 'metrics', `${date}.json`)))
}

つまり --out-root を一時ディレクトリに差し替えた瞬間、前日ファイルが存在しなくなる。 そのまま走らせると「前日比が付かない」という結果が出るが、これは偽の不合格だ。 本番では前日ファイルがあるので正常に動く。ここで「バグだ」と判断して日付計算を直しにいくと、 動いているコードを壊す。

対策は1行。走らせる前に本番の前日ファイルをコピーしておく。

mkdir -p "$TMP/analysis/metrics"
cp <本番>/analysis/metrics/<前日>.json "$TMP/analysis/metrics/"

一般化すると: 出力先を差し替えたら、そのディレクトリを入力として読む箇所を必ず grep する。 出力先と入力元が同じディレクトリを指している処理は、差し替えで黙って壊れる。

4. 本番と同じコードを走らせる

コードの版が違えば検証にならない。本番ジョブが読むのと同じ場所のコードを指定する。

# タスクスケジューラ / cron が実際に何を実行しているかを先に読む
#   Windows: (Get-ScheduledTask -TaskName <名前>).Actions
#   Linux  : crontab -l
node <本番ジョブが読むパス>/batch.mjs --dry --out-root "$TMP"

自分の作業ツリーのコードを走らせても、本番が別の worktree / 別のチェックアウトを読んでいれば無意味。 ここを取り違えると「手元では通るのに本番では落ちる」を再生産する。

5. 機械的に判定する

目視で「出ているっぽい」と言わない。grep の exit code で判定する。

# 条件1: 必要な節があるか
grep -n "^## 節A\|^## 節B\|^## 節C" "$REPORT"

# 条件2: 禁止語が0件か（exit 1 = マッチなし = 合格）
grep -n "禁止語1\|禁止語2" "$REPORT"; echo "EXIT=$?"

# 条件3: 前日比が付いているか（該当節を全部出して目で確かめる）
awk '/^## 節B/,/^## 節C/' "$REPORT"

条件2はマッチしないことが合格なので、exit code を必ず表示する。 出力が空なのは「マッチなし」かもしれないし「ファイルが無い」かもしれない。 ファイルが無いときの grep は exit 2 で、これを「0件」と読むと存在しないレポートを合格にする。

副産物: 実所要時間が測れる

この走らせ方をすると、本番の所要時間がタダで測れる。

実例: 内部タイムアウトの合計が 44 分あり、タスクの実行時間上限 40 分を超えるのではないかと 懸念されていたジョブがあった。前倒し実行で計測したところ実測16分で、上限の引き上げは不要と判明した。 上限を変更する作業（承認が要ることが多い）を丸ごと消せた。

生成物のタイムスタンプを見れば内訳も出る。

ls -la --time-style=full-iso "$TMP/analysis/"*/

やってはいけないこと

• 本番の出力ディレクトリへ書かせない。 --out-root の指定を忘れると、前倒し実行の結果が その日の正式なレポートとして残り、朝の本番実行と二重になる。
• 通知を飛ばさない。 --dry を忘れると深夜にチャットへ投稿され、翌朝それを読んだ人が 「今朝のレポート」と誤読する。
• 前倒し実行をもって「本番ジョブが動いた」と報告しない。 証明できたのは 「このコードはこの出力を出す」までで、「スケジューラが起動する」は別の条件。 時刻依存の条件は翌朝に1回確認する（前倒しで潰した分、確認は grep 1回で済む）。
• 共有ブラウザを閉じるコードに注意。 バッチがブラウザを使う場合、browser.close() が 自前起動したブラウザに対するものか、常駐させている共有ウィンドウに対するものかを先に読む。 launch() した browser を閉じるのは安全、connect() したものを閉じると常駐セッションが死ぬ。

チェックリスト

• 完了条件を「出力依存」と「時刻依存」に仕分けた
• 本番ジョブが実際に実行しているコマンドを読んだ（推測していない）
• 通知抑止フラグを付けた / 重い処理を省くフラグは付けていない
• 出力先を一時ディレクトリに差し替えた
• 出力先を入力として読む箇所を grep し、前日分をシードした
• 判定は grep の exit code で出した（ファイル不存在の exit 2 と区別した）
• 所要時間を記録した
• 時刻依存の条件だけを翌朝の宿題として残した