委譲した実装を「本番で起動される環境」で受け入れ検証する

AI エージェントに実装を委譲すると、テストは緑で返ってくる。 だがその緑は 委譲先が実行した環境での緑 でしかない。 実行環境が2つあるプロジェクト（WSL と Windows ネイティブ、コンテナとホスト、CI とローカル）では、 片方でだけ通るコードが平然と生まれ、本番の起動経路に配線した日の夜まで欠陥が隠れる。

この指示書は、その受け入れ検証を型にする。

前提となる構図

• 監督役の AI（あなた）が仕様を書き、実装は別のコーディング AI／CLI に委譲する
• 委譲先は多くの場合 Linux 系のシェルで動く
• 一方、出来上がったスクリプトを実際に起動するのはスケジューラやサービスで、 そちらはホスト OS のネイティブ実行系（例: Windows のタスクスケジューラ → PowerShell → ネイティブ node）

この差が埋まっていないと「テスト緑 → 配線 → 毎晩静かに失敗」が起きる。

手順

1. 仕様書に「本番の起動経路」を明記する

委譲の指示書に、実装の要件とは別に必ず書く。

このスクリプトは最終的に <スケジューラ名> から <シェル名> 経由で起動される。
したがって検証は <本番の実行系> でも1回実行し、その生出力を報告に貼ること。
<本番の実行系> が見つからない場合は「見つからなかった」と正直に書くこと（成功を装わない）。

「正直に書け」を明示するのは重要で、これが無いと委譲先は 自分が動かせた環境の結果だけを貼って完了を宣言する。

2. 受け入れ側（監督）が本番の実行系で自分で1回叩く

委譲先の報告は証拠として採用しない。監督が自分で実行する。

# 委譲先の環境ではなく、本番が使う実行系で
<本番の実行系> <スクリプト> --dry-run
echo "exit=$?"

これだけで、次章の欠陥はすべて表面化する。

3. 環境差で死ぬ定番3つを名指しで潰す

(a) ESM で自ファイルの場所を求めるときの URL → パス変換

// 壊れる: Windows ネイティブでは "/C:/..." が返り、join すると "C:\C:\..." になる
const dir = path.dirname(new URL(import.meta.url).pathname);

// 正しい
import { fileURLToPath } from 'node:url';
const dir = path.dirname(fileURLToPath(import.meta.url));

POSIX 系では pathname がそのまま使えてしまうため、委譲先の環境では最後まで緑になる。

(b) シェル経由でしか起動できない実行ファイル

ラッパースクリプト（.cmd / .bat / .ps1 等）は、 シェルを介さない素のプロセス生成では起動できないことがある。 子プロセスを起こす箇所は、シェル経由の起動オプションを付けるか、実体のパスを解決する。

(c) 失敗しているのに成功の終了コードを返す

$ <スクリプト> --check
ENOENT: no such file or directory, open '...'
exit=0        # ← これが本番に載ると失敗が永久に「成功」として記録される

例外を捕まえて表示している箇所で、終了コードを立て忘れていないかを必ず確認する。 無人実行に載せる前に、わざと失敗させて exit code が 0 でないことを実測する。

4. 受け入れテストに「本番環境で意味を持つ assert」を足させる

環境差は、テストの中でも表明できる。

- 既定の設定ファイルパスが実在ファイルに解決されること（fs.existsSync(DEFAULT_PATH)）
- 失敗ケースで終了コードが 0 でないこと

前者は (a) を、後者は (c) を機械的に縛る。 このテストが本番の実行系でも走ることが目的なので、テストコマンド自体も本番側で1回流す。

破壊的な変更を伴う場合の追加ゲート

生成物がファイルを書き換えるツールなら、受け入れ前に次も実測する。

• 往復無損失: 「何も変更しない」入力で走らせ、出力が入力とバイト単位で一致すること。 一致しないなら、パーサが解釈できなかった部分を黙って捨てている
• 冪等性: 2回続けて実行し、2回目が1バイトも書き換えないこと
• 競合検知: 書き込み直前に対象を読み直し、サイズと更新時刻が計画時と一致しなければ書かずに中止すること。 複数のエージェントが同じファイルを触る環境では、これが無いと他方の変更を消す
• 自動復元: 書いた後に読み直して検証し、破れていたらバックアップから戻すこと

これらは変換ツール自身の assert ではなく、別実装の検証ツールで照合する。 同じパーサで期待値を作ると、パーサのバグは絶対に検出できない。

完了条件

• 本番の実行系で --dry-run 相当が exit 0 で通った生出力がある
• わざと失敗させたときに exit code が 0 でない生出力がある
• 破壊的ツールなら、往復無損失・冪等性・競合検知・自動復元の4つを実測した記録がある

なぜこの型が要るか

「テストが緑」は そのテストを走らせた環境で緑 という意味しかない。 委譲は実装の速度を上げるが、検証の責任は監督から移らない。 受け入れ検証を本番の起動経路に合わせるだけで、 「配線した日から毎晩静かに失敗し、数週間後に気付く」種類の障害はほぼ消える。