# AI の出力を止めるゲート hook が誤爆した時の直し方 テキストマッチで AI の応答を止める hook（「手順が足りない依頼は止める」「情報の無い依頼は止める」等）は、 **必ず誤爆する**。誤爆すると AI は正しい仕事をしているのに応答を出せず、人は理由が分からないまま止まる。 放置すると「とりあえず逃がし弁を毎回書く」運用になり、ゲートが死ぬ。 このMDは、誤爆を **場当たりの語彙追加ではなく、真因を特定して直す**手順。 Claude Code / Cursor / 自作エージェントなど、Stop 相当のフックを持つ環境ならそのまま使える。 --- ## 0. 前提 - ゲート hook は「AI の最後の応答テキスト」を読み、条件に合わなければ非ゼロ終了して応答を差し戻す。 - 誤爆 = **止めるべきでない応答を止めた**。過小検知（止めるべきを通した）とは対策が逆なので混同しない。 --- ## 1. 誤爆の本文を「逐語で」回収する（最重要） **やってはいけない**: 記憶や要約から再現テストを書くこと。合成した短文では**再現しない**。 誤爆は文章の構造（後述）で起きるので、原文でないと条件が揃わない。 会話ログ（JSONL 等）から、hook が発火した直前の assistant テキストを機械的に抜く。 ```js // transcript.jsonl から「hook のエラーメッセージが出た行」の直前の assistant 本文を取り出す import fs from 'node:fs'; const lines = fs.readFileSync(process.argv[2], 'utf8').split(/\r?\n/).filter(Boolean); const hit = lines.findIndex((l) => l.includes('') && l.includes('該当箇所')); for (let i = hit - 1; i >= 0; i--) { const o = JSON.parse(lines[i]); if (o.type !== 'assistant') continue; const t = (o.message?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('\n'); if (t.trim()) { fs.writeFileSync('fixtures/false-positive-1.md', t, 'utf8'); break; } } ``` 抜いた本文は **fixture ファイルとしてリポジトリにコミット**する。 テストコードの中にテンプレートリテラルで貼ると、バッククォートや `${` のエスケープで壊れる。 ファイルに置いて `fs.readFileSync` で読むこと。 --- ## 2. 真因を特定する（仮説で直さない） 誤爆メッセージが指す「該当箇所」は、**原因の場所とは限らない**。 多くの実装は「違反したブロックの1行目」を表示するので、原因の文ではなく見出し行が出る。 まず、どの文で発火したかを実際に出させる。 ```js const r = findViolation(fs.readFileSync('fixtures/false-positive-1.md', 'utf8')); console.log(r.sentences ?? r.blocks.map((b) => b.split('\n')[0])); ``` ### 実際にあった真因トップ3 | 真因 | 症状 | なぜ起きるか | |---|---|---| | **Markdown 表が1ブロックになる** | 表のヘッダ行が「該当箇所」として出る | ブロック分割を空行で行う実装が多い。表には空行が無いので**表全体が1ブロック**になり、セル1つの中の文が表全体を違反にする | | **引用を実物と数える** | 「〜してください」を**例示した**行で止まる | 鉤括弧やインラインコードの中の文は「依頼の引用」であって依頼ではない。検証結果の表や仕様の説明で頻出 | | **要求そのものが不要な種類** | 満たしようのない条件を要求する | 例: 「その場で実行できる URL を書け」というゲートが、URL の存在しない依頼（「スクショを1枚ください」）まで止める | 3つ目は特に危ない。**別のルールが要求している行動を、hook が塞いでいる**ことがある （「自分で見られない画面はスクショをもらえ」と決めておきながら、その依頼を hook が止めていた）。 ゲートを足す時は、**社内の他のルールが命じる行動が通るか**を必ず1回試す。 --- ## 3. 直す（範囲を最小にする） 誤爆を消すために閾値やトリガー語を丸ごと緩めない。**過小検知に変わるだけ**。 真因ごとにピンポイントで例外を切る。 ### 3-1. 引用の中身を判定から外す ```js export function stripQuoted(s) { return s .replace(/“[^”]*”/g, '“”').replace(/"[^"]*"/g, '""') .replace(/「[^」]*」/g, '「」').replace(/『[^』]*』/g, '『』') .replace(/`[^`]*`/g, '``'); // インラインコード } ``` **罠1: 剥がす順番。** 文に切ってから剥がすと、引用の中に句点があった場合に ``` | 検証項目 | 「次のコマンドを実行してください。 ← ここで文が切れる ``` という**閉じ括弧を失った断片**になり、`/「[^」]*」/` が一致しなくなる。 **必ず「文に切る前・ブロック単位」で剥がす。** **罠2: 剥がした文字列で「情報の有無」を判定しない。** 剥がすとインラインコード内のコマンドも消えるので、 「実行できる情報がある/ない」の判定は**必ず元のテキスト**で行う。剥がすのは*依頼かどうかの判定*だけ。 **罠3: 括弧はラベルにも使う。** `「設定」を開いてください` は中身を空にしても動詞が外に残るので、 検出され続ける。これは**正しい挙動**なので壊さないこと（テストで固定する）。 ### 3-2. 「満たしようがない依頼」を対象外にする 条件は2つの AND で書く。片方だけだと抜ける。 ```js // (a) その種類にあたる かつ (b) 追加情報が要る動作を含まない if (EXEMPT_KIND.test(sentence) && !NEEDS_INFO_ACTION.test(sentence)) return false; ``` `スクショを貼ってください` は通す。`画面を開いてスクショを貼ってください` は**開く先の URL が要る**ので止める。 **日本語の罠: 動詞は「て形」まで書き下す。** `(?:貼|送)ください` は `貼ってください` に**一致しない**。実際にこれで1度落ちた。 ```js /(?:貼(?:って|り付けて)|送って|共有して|見せて)(?:ください|下さい|もらえますか|いただけますか)/ ``` ### 3-3. エラーメッセージに「引っかかった文そのもの」を出す これを怠ると、次の誤爆の診断がまた1時間かかる。 ```js sentences.push(handoffSentences[0]); // 検出時に保存しておく // 表示側 sample = result.sentences?.[0] ?? result.blocks[0].split('\n')[0]; ``` --- ## 4. 2種類のテストを両方書く | 種類 | 何を守るか | |---|---| | 判定関数の単体テスト | 誤爆 fixture が通ること、既存の検出が壊れていないこと | | **stdin → exit code の契約テスト** | hook として起動した時に**どこを読むか**。関数単体テストでは絶対に出ない | 契約テストは実際にプロセスを起動する。 ```js function runHook(assistantText) { const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gate-')); const transcript = path.join(dir, 't.jsonl'); fs.writeFileSync(transcript, JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: assistantText }] }, }) + '\n'); return new Promise((resolve) => { const child = execFile(process.execPath, [HOOK], (err, _o, stderr) => { resolve({ code: err ? (err.code ?? 1) : 0, stderr: stderr || '' }); }); child.stdin.end(JSON.stringify({ transcript_path: transcript })); }); } ``` **誤爆ケース（exit 0 期待）と過小検知ケース（exit 2 期待）を必ずセットで書く。** 誤爆だけ直すと、次の人が「緩めればいいのか」と学習してゲートが死ぬ。 --- ## 5. 「直った」の定義 — 配布先のファイルが変わるまで完了ではない hook は各マシンへ配布されて動く。手元の作業コピーでテストが緑でも、**配布先は古い版のまま**。 1. 正本（保護ブランチ）へ PR → マージ 2. 各マシンの同期を1回走らせる 3. **配布先の実ファイル**のハッシュが変わったことを確認する 4. **配布先のファイルに対して**テストを流し直す ```bash md5sum <配布先>/gate.mjs # 同期前 <同期コマンド> md5sum <配布先>/gate.mjs # 同期後（変わっていること） node --test <配布先>/gate.test.mjs <配布先>/gate.contract.test.mjs ``` 実話: 修正 PR の完了報告に「真因の表」を書いたら、**まだ配布されていない旧版がその表で報告自身を止めた**。 同じ本文を旧版と新版で突き合わせて `BLOCK` / `PASS` を出すのが、一番わかりやすい証拠になる。 ``` 配布中の旧版 : BLOCK / 該当 "| 止められていた文 | 真因 |" 新版 : PASS ``` --- ## 6. 実装を LLM に委譲する時の注意 安いモデルへ委譲すると速いが、**日本語のコメントと文字列を壊す**ことがある。 - 「コメントを消すな」と書いても消す。→ **論理差分だけ受け取り、自分のファイルへ当てる** - 助詞1文字が別言語の字に化ける（`の` → `的` 等）。→ マージ前に既知語を grep で当てる - 1回目で落ちたら、2回目の指示に **「前回これで不合格になった」と失敗出力を貼る**と通る 修正が2ステップ以上なら、**1ステップずつテストを回して**から次へ進む。まとめて投げると原因が混ざる。 --- ## チェックリスト - [ ] 誤爆本文を逐語で fixture 化した（記憶から書き直していない） - [ ] 「該当箇所」ではなく**実際に引っかかった文**を出させて真因を特定した - [ ] 直したのは真因ごとの最小の例外で、閾値やトリガー語を丸ごと緩めていない - [ ] 引用剥がしは「文に切る前」、情報判定は「元のテキスト」 - [ ] 動詞のて形を書き下した - [ ] 過小検知ケースを exit code で確認した - [ ] 正本マージ → 同期 → **配布先のファイルのハッシュが変わった**ことまで見た ---