正しく動く検知器が一度も発火しない — 「検知力」ではなく「いつ聞かれるか」を先に測る

これは何の指示書か

「二重作業を止める」「危険な操作を止める」ための検知の仕組みを作ったのに、現場では事故が起き続けている。 テストは全部 green、コードを読んでも間違いが見つからない。そういう時の切り分け手順。

結論を先に書く。検知力（検知できるか）と、検知される状況に置かれているか（いつ聞かれるか）は別の問いで、 テストは前者しか測らない。事故が続いているのに検知力が正常な時、原因はほぼ後者にある。

想定読者: AI エージェント、または AI に作業させている人。 所要: 30〜60分（切り分け20分＋修正10分＋検証20分）。

---

症状の見分け方

次が同時に成り立っていたら、この指示書の対象。

• 検知の仕組みは実装済みで、起動経路（hook / middleware / CI ステップ等）にも登録されている
• その仕組みの自前テストは全部 pass している
• それでも防ぎたかった事故が繰り返し起きている（回数を数えられるなら数える。ここが効き目の測定基準になる）
• ログを見ても「検知しようとして失敗した」形跡が無い。そもそも何も出ていない

最後の1点が重要。誤検知でも取りこぼしでもなく「無音」なら、呼ばれていないか、呼ばれて即 return している。

---

手順1: 実物を食わせて検知力を単独で測る（20分）

まず「検知力が壊れている」説を潰すか確定させるかする。ここを飛ばして直し始めると、 検知力とタイミングの両方をいじってしまい、何が効いたか分からなくなる。

やり方

1. 事故が実際に起きた時の入力を、加工せずそのまま用意する。 ログ、トランスクリプト、リクエストのダンプ、DBのレコード — 現物をコピーする。 🔴 手で書き起こしたサンプルを使わない。 手写しは無意識に「検知しやすい形」へ寄り、偽の合格を作る。
2. 検知器をその入力だけで動かす。本体を import すると初期化が走って邪魔なら、 子プロセスとして起動するのが確実（環境変数で入力の場所を差し替えられるなら、それを使う）。
3. 出力を見る。

# 例: 入力の場所を環境変数で差し替えて、検知器を子プロセスとして起動する
INPUT_DIR=/tmp/replay/real-data \
  node path/to/detector.js --event <実際に来るイベント名> --id <対象のID> < /dev/null

読み方

• 警告が出た → 検知力は正常。原因はタイミング。手順2へ。
• 出ない → 検知力の問題。この指示書の対象外（閾値・正規化・比較ロジックを疑う）。

実例: あるセッション衝突検知器にこれをやったら、類似度 0.86 で正しく警告した。 一方、現場では 8 回素通りしていた。この時点で「検知力を直す」という選択肢が消え、調査が半分に減った。

---

手順2: 「判断が決まる瞬間」を1つ名指しする（10分）

ここが指示書の核心。次の2つを別々の文で書き出す。

1. 検知器が呼ばれる瞬間（コード上の事実。登録されているイベント名を読む）
2. 防ぎたい事故が確定する瞬間（人間の言葉で。「◯◯を選んだ時点」「◯◯を押した時点」）

この2つがズレていれば、それが原因。

よくあるズレ方

事故が確定する瞬間	検知器が呼ばれる瞬間	結果
選ぶ時	選んだ結果を宣言した後	宣言前は必ず無音
送信ボタンを押す時	送信が完了した後	事後通知にしかならない
設定を書き換える時	次回起動時	1サイクル遅れる
発注を決める時	決裁が回り始めた後	撤回コストが跳ね上がる

🔴 最頻出の形: 「情報が無いから黙る」分岐

検知器の冒頭にはたいてい、こういうガードがある。

const own = 自分の申告を探す(...);
if (!own) return;        // ← 申告がまだ無い。何も比較できないので黙って終わる

一見正しい。比較対象が無いのだから比較できない。しかしここが穴になる。

なぜなら、**申告がまだ無い状態とは「これから選ぶ状態」**だからだ。 つまり 一番危険な瞬間が、このガードによって必ず素通りする。 そして検知器は申告後にしか動かないので、警告は常に「もう決めた後」に届く。降りるコストが上がった後に。

「情報が無い」を「危険が無い」と読み替えていないかを、すべての早期 return で確認する。

なぜテストが捕まえないか

テストの fixture は必ず「自分が既に申告している」状態から始まる。申告前という状態が fixture に存在しない。 だから穴はテストの外側に開く。テストが green なのは、穴の無い領域だけを見ているから。

---

手順3: 直す — 黙るのをやめて「材料」を出す（10分）

情報が足りなくて判定できない時、判定の代わりに材料を出す。

if (!own) {
  // 判定はできない。しかし「これから選ぶ人」に見せるべき材料はある
  if (これから選ぶ局面のイベントか(event)) {
    const others = 他の稼働中の申告を新しい順に();
    if (others.length > 0) 一覧を出す(others.slice(0, 5));   // 0件なら黙る
  }
  return;
}
// ここから下（本来の判定）は1文字も変えない

設計の要点:

• 出す局面を絞る。毎回の細かい呼び出しで出すとノイズになって読まれなくなる。 「これから選ぶ」局面のイベントだけに限る。
• 0件なら黙る。何も起きていない時に出力しない。これが守れていれば人は出力を信用し続ける。
• 件数に上限を置く（5件程度）。新しい順に並べる。
• 既存の判定経路は1文字も変えない。変更を早期 return の分岐の中だけに閉じる。 こうすると、後で「この変更が壊したのか」を切り分ける必要が無くなる。
• 状態を記録するフラグ（latch / 既読マーク）をここで立てない。 申告が揃った後に本来の判定をやり直させる必要があるため、立てると二度と判定されなくなる。

---

手順4: 検証 — 同一入力の前後比較（20分）

修正後のテストが通ったことは証拠にならない。 修正と一緒にテストも書いたなら、それは自作自演になり得る。

証拠は次の形で作る。

(a) 前後比較（これが本体）

同じ入力を、修正前のコードと修正後のコードの両方に食わせて、出力を並べる。

# 修正後
node <新> --event <選ぶ局面のイベント> --id <新規> < /dev/null
# 修正前（VCS から一時的に戻す。戻し忘れないこと）
git stash && node <旧> --event <同じ> --id <同じ> < /dev/null ; git stash pop

	同一入力
修正前	出力ゼロ
修正後	該当を一覧表示

入力は手順1で用意した実物を使う。ここで合成データに戻すと、証拠の価値が落ちる。

(b) 対照群 — 出てはいけない場面で出ないこと

「出るようになった」だけでは不十分。騒がしくなっただけかもしれない。次を全部確認する。

• 対象が0件 → 無音
• 対象はあるが古すぎる（有効期間外）→ 無音
• 関係ない内容 → 無音
• 絞ったはずの局面以外のイベント → 無音、かつ状態フラグも書かれていない

(c) 本番経路での読み戻し

最後に、実際に登録されているコマンドそのものを、実際のデータに対して実行する。 テスト用のパスやコピーではなく、起動設定に書かれている通りのコマンドで。

配布の仕組みがあるなら（同期・デプロイ・キャッシュ）、そこを通った後のファイルが 意図したものと一致するかも読み戻す。「マージした」は「動いている」ではない。

---

手順5: 欠陥を固定していたテストの扱い

この修正をすると、既存のテストが1つ落ちることがよくある。

✗ 申告が無ければ静かに終了する

このテストは、いま直した欠陥を「正しい挙動」として固定していたもの。

🔴 消さない。範囲を絞って残す。

• 誤: テストごと削除する → 「無音であるべき場面でも喋る」退行を誰も止められなくなる
• 正: 「申告が無く、かつ対象も0件なら無音」へ絞り、テスト名も実態に合わせて変える

「テストが邪魔だから消す」と「テストが古い前提を固定しているから絞る」は別物。 絞った後も無音の検証が1つ残っているかどうかで見分ける。

---

チェックリスト

• 実物の入力で検知力を単独で測った（手写しの fixture を使っていない）
• 「事故が確定する瞬間」と「検知器が呼ばれる瞬間」を別々の文で書き出し、ズレを特定した
• すべての早期 return について「情報が無い＝危険が無い」と読み替えていないか確認した
• 修正を早期 return の分岐内だけに閉じ、既存の判定経路を変えていない
• 同一入力の前後比較で、修正前が無音・修正後が検知することを示した
• 対照群4種（0件／期限外／無関係／対象外イベント）が全部無音であることを確認した
• 実際に登録されているコマンドを実データで走らせて読み戻した
• 欠陥を固定していた既存テストを、削除ではなく範囲を絞って残した

---

一般化: この型が当たる他の場面

「情報が揃ってから判定する」設計はどこにでもあり、揃う前が一番危ないという構造も共通している。

• 承認フロー: 申請内容が確定してから重複チェック → 起案中に同じ申請が並走する
• デプロイガード: デプロイ開始後に整合性チェック → 止めるコストが最大の所で止める
• 在庫引当: 注文確定後に在庫照会 → 確定前に見せれば選び直せた
• 権限チェック: 操作実行時に判定 → 操作を組み立てる前に「できない」と分かれば手戻りゼロ

いずれも直し方は同じ。判定できない局面では、判定の代わりに材料を出す。