追加したテストが「本当にその不具合を捕まえるか」を対照群で確かめる

これは何

バグを直して、テストを足して、緑になった。それだけでは「直した」証拠にならない。 そのテストは、直す前のコードに当てても緑かもしれない。実際それは頻繁に起きる。

この指示書は、テストを足したあとに 直した箇所をわざと無効化して、テストが赤くなることを確かめる 手順（対照群 / mutation check）を、AI エージェントに自動で回させるためのもの。

対象: 言語問わず。例は Node.js（node --test）だが、考え方と落とし穴は共通。

なぜ必要か（実際に起きた2つの素通り）

1. 置換が当たっていないのに「合格」と読んだ

対照群スクリプトは「直した行を元に戻す → テストを走らせる → 赤くなるはず」という作りにする。 ところが置換が当たらなかった場合、テストは一度も走らない。 にもかかわらずスクリプトが黙って次へ進むと、人は「対照群をやった」と記憶する。

実際の原因は改行コードだった。対象ファイルが CRLF なのに、検索パターンを \n 固定で書いたため、 複数行パターンだけが一致しなかった。単一行のパターンは当たったので 「3本中1本は赤くなった」と部分的に成功して見え、余計に気づきにくかった。

対策:

• 置換前に find が当たるかを判定し、当たらなければ 「不成立」 として数える（合格でも不合格でもない）
• 置換後に「中身が実際に変わったか」も確認する（before === after なら不成立）
• 複数行パターンは \r?\n で書く

2. テストが、実装を通らない別経路で緑になっていた

「子プロセスが失敗したとき、その標準エラー出力を拾えるようにした」という修正を検証するテストを、 こう書いた（擬似コード）:

const marker = 'SOME_UNIQUE_MARKER';
args = ['-e', `console.error("${marker}"); process.exit(7)`];
...
assert(result.message.includes(marker));

これは 修正を元に戻しても緑のままだった。

理由: 多くの言語の「コマンド実行に失敗した」例外は、メッセージに コマンドライン全文を含む（Command failed: <実行ファイル> <引数全部>）。 marker を引数の中に書いていたので、標準エラー出力を一度も読まなくても marker が例外メッセージに混入し、assert が通っていた。

対策: 期待する文字列が、実装を通らない経路で出力に到達しないかを先に潰す。 このケースでは marker を引数に置かず、base64 を引数に置いて子が実行時に復号する:

const marker = 'SOME_UNIQUE_MARKER';
const encoded = Buffer.from(marker, 'utf8').toString('base64');
args = ['-e', `process.stderr.write(Buffer.from("${encoded}",'base64').toString()); process.exit(7)`];

// 前提そのものをテストに書く
assert(!args.join(' ').includes(marker), 'marker が引数に混入している＝検出器として成立しない');
assert(result.message.includes(marker));

同型の穴: 環境変数名・ファイルパス・コマンド名・設定キー名を assert するテストは、 その文字列がコマンドラインやエラー文言やログ書式に現れるなら同じ罠にはまる。

手順（AI エージェントにそのまま渡す）

1. 正本を退避する。 対照群は対象ファイルを書き換えるので、まず退避コピーを作る。 🔴 未コミットの変更がある場合、git checkout / git restore で戻すと作業が消える。 復元は必ず退避コピーからの上書きで行う。
2. 素の状態で全テストを走らせ、pass/fail を記録する。 ここが赤いなら対照群に進まない。
3. 直した箇所ごとに1つずつ無効化する。 1回に1箇所。複数同時に壊すと、どのテストが どの欠陥を見ているのか分からなくなる。
4. 各回について記録する:
   • 置換が当たったか（当たらなければ「不成立」）
   • pass / fail の数
   • 落ちたテスト名の一覧
   • 期待していたテストが実際に落ちたか
5. 毎回、退避コピーから復元して緑に戻ることを確認する。
6. 最後に、対象ファイルが退避コピーとバイト一致することを確認する。
7. 「不成立」または「期待したテストが落ちなかった」が1件でもあれば、合格と報告しない。

雛形（Node.js）

import { readFileSync, writeFileSync, copyFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';

const TARGET = '<対象ファイル>';
const BACKUP = '<退避コピー>';
const NL = '\\r?\\n';   // CRLF でも当たるように

const CASES = [
  { name: 'A: <直した内容>を元に戻す',
    find: new RegExp(`<複数行なら ${NL} を使う>`),
    replace: '<元の実装>',
    expect: '<赤くなるはずのテスト名の一部>' }
];

function runTests() {
  try { return execFileSync('node', ['--test', '<テストファイル>'],
      { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 }); }
  catch (e) { return (e.stdout || '') + (e.stderr || ''); }
}
function summarize(out) {
  const pass = (out.match(/^. pass (\d+)/m) || [])[1] ?? '?';
  const fail = (out.match(/^. fail (\d+)/m) || [])[1] ?? '?';
  const failing = [...new Set([...out.matchAll(/^ *✖ (.+?) \(/gm)].map(m => m[1]))];
  return { pass, fail, failing };
}

let unresolved = 0;
copyFileSync(BACKUP, TARGET);
let s = summarize(runTests());
if (s.fail !== '0') { console.log('ベースラインが赤い。中止。'); process.exit(1); }

for (const c of CASES) {
  copyFileSync(BACKUP, TARGET);
  const src = readFileSync(TARGET, 'utf8');
  if (!c.find.test(src)) { console.log(`${c.name}: 不成立（置換対象なし）`); unresolved++; continue; }
  const mutated = src.replace(c.find, c.replace);
  if (mutated === src) { console.log(`${c.name}: 不成立（中身が変わらない）`); unresolved++; continue; }
  writeFileSync(TARGET, mutated, 'utf8');
  s = summarize(runTests());
  const hit = s.failing.some(f => f.includes(c.expect));
  console.log(`${c.name}: pass=${s.pass} fail=${s.fail} / ${hit ? '✅ 期待どおり赤' : '🔴 捕まえていない'}`);
  s.failing.forEach(f => console.log(`   - ${f}`));
  if (!hit) unresolved++;
  copyFileSync(BACKUP, TARGET);
}
copyFileSync(BACKUP, TARGET);
console.log(unresolved === 0 ? '✅ 全対照群が成立し期待どおり赤くなった'
                             : `🔴 未解決 ${unresolved} 件（合格と扱わない）`);

併せて避ける書き方

assert を try/catch で包まない。 次の形は例外を握り潰して無条件 pass になる:

try { assert.equal(a, b); assert.equal(c, d); } catch { assert.ok(true); }   // 絶対に書かない

後片付けが要るなら try { ... } finally { ... }（catch を書かない）。 AI に委譲する際、仕様書に「まとめて判定してよい」と書くとこの形が生まれやすいので、 「判定は catch の外」と明示する。

効果

• 「テストが緑」から「そのテストは実際にこの欠陥を捕まえる」へ、証拠の質が上がる
• 修正を将来デグレさせたとき、そのテストが確実に鳴ることが事前に分かっている
• 対照群が赤くならなければ、テストかモックのどちらかが実物から乖離しているサイン