# 正しく動く検知器が一度も発火しない — 「検知力」ではなく「いつ聞かれるか」を先に測る ## これは何の指示書か 「二重作業を止める」「危険な操作を止める」ための検知の仕組みを作ったのに、**現場では事故が起き続けている**。 テストは全部 green、コードを読んでも間違いが見つからない。そういう時の切り分け手順。 結論を先に書く。**検知力（検知できるか）と、検知される状況に置かれているか（いつ聞かれるか）は別の問い**で、 テストは前者しか測らない。事故が続いているのに検知力が正常な時、原因はほぼ後者にある。 想定読者: AI エージェント、または AI に作業させている人。 所要: 30〜60分（切り分け20分＋修正10分＋検証20分）。 --- ## 症状の見分け方 次が同時に成り立っていたら、この指示書の対象。 - 検知の仕組みは実装済みで、起動経路（hook / middleware / CI ステップ等）にも登録されている - その仕組みの自前テストは全部 pass している - **それでも防ぎたかった事故が繰り返し起きている**（回数を数えられるなら数える。ここが効き目の測定基準になる） - ログを見ても「検知しようとして失敗した」形跡が無い。**そもそも何も出ていない** 最後の1点が重要。**誤検知でも取りこぼしでもなく「無音」なら、呼ばれていないか、呼ばれて即 return している。** --- ## 手順1: 実物を食わせて検知力を単独で測る（20分） まず「検知力が壊れている」説を**潰すか確定させるか**する。ここを飛ばして直し始めると、 検知力とタイミングの両方をいじってしまい、何が効いたか分からなくなる。 ### やり方 1. **事故が実際に起きた時の入力を、加工せずそのまま用意する**。 ログ、トランスクリプト、リクエストのダンプ、DBのレコード — 現物をコピーする。 🔴 **手で書き起こしたサンプルを使わない。** 手写しは無意識に「検知しやすい形」へ寄り、偽の合格を作る。 2. 検知器を**その入力だけで**動かす。本体を import すると初期化が走って邪魔なら、 **子プロセスとして起動する**のが確実（環境変数で入力の場所を差し替えられるなら、それを使う）。 3. 出力を見る。 ```bash # 例: 入力の場所を環境変数で差し替えて、検知器を子プロセスとして起動する 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サイクル遅れる | | 発注を決める時 | 決裁が回り始めた後 | 撤回コストが跳ね上がる | ### 🔴 最頻出の形: 「情報が無いから黙る」分岐 検知器の冒頭にはたいてい、こういうガードがある。 ```js const own = 自分の申告を探す(...); if (!own) return; // ← 申告がまだ無い。何も比較できないので黙って終わる ``` 一見正しい。比較対象が無いのだから比較できない。**しかしここが穴になる。** なぜなら、**申告がまだ無い状態とは「これから選ぶ状態」**だからだ。 つまり **一番危険な瞬間が、このガードによって必ず素通りする**。 そして検知器は申告後にしか動かないので、**警告は常に「もう決めた後」に届く**。降りるコストが上がった後に。 **「情報が無い」を「危険が無い」と読み替えていないか**を、すべての早期 return で確認する。 ### なぜテストが捕まえないか テストの fixture は必ず「自分が既に申告している」状態から始まる。**申告前という状態が fixture に存在しない**。 だから穴はテストの外側に開く。テストが green なのは、穴の無い領域だけを見ているから。 --- ## 手順3: 直す — 黙るのをやめて「材料」を出す（10分） 情報が足りなくて判定できない時、**判定の代わりに材料を出す**。 ```js 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) 前後比較（これが本体） **同じ入力**を、**修正前のコード**と**修正後のコード**の両方に食わせて、出力を並べる。 ```bash # 修正後 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件／期限外／無関係／対象外イベント）が全部無音であることを確認した - [ ] 実際に登録されているコマンドを実データで走らせて読み戻した - [ ] 欠陥を固定していた既存テストを、削除ではなく範囲を絞って残した --- ## 一般化: この型が当たる他の場面 「情報が揃ってから判定する」設計はどこにでもあり、**揃う前が一番危ない**という構造も共通している。 - 承認フロー: 申請内容が確定してから重複チェック → 起案中に同じ申請が並走する - デプロイガード: デプロイ開始後に整合性チェック → 止めるコストが最大の所で止める - 在庫引当: 注文確定後に在庫照会 → 確定前に見せれば選び直せた - 権限チェック: 操作実行時に判定 → 操作を組み立てる前に「できない」と分かれば手戻りゼロ いずれも直し方は同じ。**判定できない局面では、判定の代わりに材料を出す。** ---