同じ表が2箇所にある状態を、AIに委譲して「挙動を1ビットも変えずに」片方へ寄せる

対象: コーディングAI（Claude Code / Codex / Cursor など）に挙動不変のリファクタを任せたい人。 「片方だけ古くなる二重定義」を消す作業は、テストが通っただけでは終わっていない。実データでの 出力一致まで機械で確かめる手順を書く。

何が問題か

同じ知識が2箇所にあると、片方を更新した人がもう片方を知らずに必ずズレる。典型:

• ツールAは定数を直書き、ツールBは同じ内容を実行時にAPIから導出
• 本体は一覧を持ち、テストはその一覧を手写しした fixture を持つ

寄せる作業そのものは単純だが、危ないのは「単純だからテストが緑なら良い」と判断すること。 導出に変えると順序・型・欠損時の挙動が静かに変わる。出力が変われば下流の集計が狂う。

手順

1. 着手前にベースラインを2種類取る

# (a) テストの現状（件数を記録する。"全部緑" では後で比較できない）
node --test "test/*.test.mjs"   > baseline-tests.txt
node --test "tools/*.test.mjs" >> baseline-tests.txt

# (b) 実データでの出力。JSON を吐くフラグがあるならそれを保存する
<対象ツール> --json > before.json

(b) が要る。テストは「作者が想像した入力」しか通らないが、リファクタが壊すのは 本番データの端（欠損・空配列・想定外の名前）だから。

2. 差分を機械比較するスクリプトを先に書く

後で書くと「だいたい合っている」で済ませてしまう。着手前に書く。

import fs from 'node:fs';
const [a, b] = process.argv.slice(2).map(p => JSON.parse(fs.readFileSync(p, 'utf8')));
const KEYS = ['total', 'sold', 'blocked', /* 比較する全項目を明示的に並べる */];
let diffs = 0;
// 配列の要素数・キーの有無・値を、キー名を出しながら比較する
// （deepEqual 一発ではなく「どの項目が変わったか」を印字する。原因の切り分けが変わる）
process.exit(diffs === 0 ? 0 : 1);

assert.deepEqual 一発でも一致は分かるが、どの項目がどう変わったかが出ないと 「意図した変更」と「事故」を切り分けられない。

3. 委譲の指示書に「変えない物」を列挙する

読み取り専用のブリッジ越しにAIを使う場合、対象ファイルの全文を指示書に同梱する （AIがファイルを読めない環境では、パスだけ書いても推測で書かれるか、作業が止まる）。 指示書には最低限これを書く:

• 出力してよいファイル名（それ以外は「変更しない・出力しない」と明示）
• 変更しない関数・出力・終了コードの一覧
• 期待する検証（AIは実行できないので「期待値」として書く）

4. 落とし穴: 「既存の手書きの表はそのまま残せ」と書くな

これで1回踏んだ。テスト内の期待値が手書きの配列で、導出結果と中身は同じだが順序が違った。

// 手書き（人が書いた見やすい順）
['a1', 'a2', 'a3', 'b1', 'c1', 'c2']
// 導出（Object.keys は整数風キーを数値昇順で返す）
['a1', 'a2', 'a3', 'c1', 'c2', 'b1']

集合としては同一。実データの出力も完全に一致した。落ちたのはテストの期待値だけ。 つまり実装は正しいのに fail が出る＝偽 fail で、原因の切り分けに時間を取られる。

順序に意味が無い一覧の期待値は、正本から導出して書く。

// ✗ 手写し
assert.deepEqual(resolved['全部入り'], ['a1', 'a2', 'a3', 'b1', 'c1', 'c2']);
// ✓ 導出（正本が増えても勝手に追随する）
assert.deepEqual(resolved['全部入り'], Object.keys(SOURCE));
assert.equal(Object.keys(SOURCE).length, 6);   // 件数だけは固定して「空でも通る」を防ぐ

件数の assert を1行足すのが要点。導出だけにすると、正本が空になっても通ってしまう。

5. 導出に変えたら「取れなかったとき」を決める

直書きは失敗しないが、導出はAPI呼び出しなので失敗する。既に同じ導出をしている別のツールと 同じ縮退にそろえる（片方が例外で落ち、もう片方が黙って0件になる、が最悪）。

let table = {};
try {
  const res = await fetchSource();
  const resolved = derive(res, known);
  table = resolved.table;
  if (resolved.unknown.length) {
    // 解決できなかった物は黙って捨てず、必ず名前を出す
    console.error(`構成を解決できない項目があります（数えません）: ` +
      resolved.unknown.map(u => `${u.id}=${u.name}`).join(', '));
  }
} catch (e) {
  console.error(`定義を取得できなかった。この分類は数えない: ` + String(e?.message ?? e).slice(0, 120));
}

「取れなかった」と「0件だった」は別物。ログで区別できるようにしておくと、後日の 「なぜ数が合わないのか」が1分で終わる。

6. 受け入れ判定（この5つが揃うまで完了と言わない）

判定	コマンド	合格
構文	node --check <各ファイル>	エラー無し
テスト	node --test …	ベースラインの件数以上・fail 0
実データ	node compare.mjs before.json after.json	差分 0
仕様外の改変	git status --short	指示したファイル以外 0 件
残骸	ls *.bak-*	AIブリッジが作るバックアップを消したか

4番目が重要。委譲したAIは頼んでいないファイルを直すことがある。件数で数える。

なぜ「テストが緑」で終わらせてはいけないか

このリファクタで実際に起きたこと:

• テストは緑になった（新テストも足した）
• しかしテスト内の期待値だけが順序違いで落ち、実データの出力は完全に一致していた

もし逆（テストが緑・実データが不一致）だったら、テストだけ見て出荷していた。 テストは自分が想像した入力しか守ってくれない。 挙動不変を名乗るなら、 本番の入力で before/after を機械比較する1回が要る。

使い回せる形

1. baseline-tests.txt と before.json を作業ディレクトリに残す（後で「本当に同じだったか」を再確認できる）
2. 比較スクリプトは汎用にして次回も使う
3. 指示書・ベースライン・結果を1つのフォルダにまとめてコミットする。 次に同じ二重定義を見つけた人が、同じ手順をなぞれる