# 委譲した実装を「本番で起動される環境」で受け入れ検証する 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 → パス変換** ```js // 壊れる: 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つを実測した記録がある ## なぜこの型が要るか 「テストが緑」は **そのテストを走らせた環境で緑** という意味しかない。 委譲は実装の速度を上げるが、**検証の責任は監督から移らない**。 受け入れ検証を本番の起動経路に合わせるだけで、 「配線した日から毎晩静かに失敗し、数週間後に気付く」種類の障害はほぼ消える。 ---