## 運用ルール強制 hook が本番で壊れる3つの型と、その検証方法 前提: 「ルール文を足しても守られない。守らせたいなら実行を機械的に止める(Stop hook)」という設計は既知。この記事は「作った後に必ず起きる壊れ方」を扱う。 --- ## 型1: 部分一致による誤爆(言及と実行を区別できない) ### 症状 禁止語・トリガー語を本文に部分一致でgrepすると、「その語について説明している文」まで検知して止まる。 実例: 手作業依頼を検出する hook が、自分の完了報告——「手作業を頼む前に検証する、と記録した」——で発火し、応答が出せなくなった。 さらに悪化するパターンは、表・引用・コードブロックの中に手順例を貼っただけで発火するケース。ユーザーが「例えばこの禁止行為をやったらどうなる?」と質問しただけでも止まる。 ### 直し方 - (a) トリガーは「依頼の言い回し」だけに絞る。判定語を許可する。単語単位ではなく、**命令形+人称**のパターンで検知する(例:「〜してください」「押してください」)。 - (b) 判定対象からコードフェンス・引用・表を除去してから評価する。 - (c) 過去の話法(「〜と記録した」「〜だった」「〜と書いた」)を除外する。 ```python # 擬似コード: トリガー判定の絞り込み def should_block(text): cleaned = strip_code_blocks_and_quotes(text) if is_past_tense_report(cleaned): # 「〜と記録した」等 return False return contains_command_pattern(cleaned, ["ください", "して", "依頼する"]) ``` --- ## 型2: 読む範囲の間違い(スコープバグ) ### 症状 transcript を末尾から遡って集めると「1つ前のユーザーターン」まで拾ってしまう。今のターンでは何も悪いことをしていないのに、前のターンの不備で止まる。 逆に範囲を狭めすぎると、会話の流れを無視して全部すり抜ける。 ### 重要 この不具合は**判定関数(judge)の単体テストでは絶対に出ない**。入力を人が作るから。判定関数は「渡された文字列」に対してだけ正しく動き、「どの文字列を渡すか」の範囲選択ロジックのバグは、統合テストまで表面化しない。 ### 直し方 「最後のユーザー発言より後ろ」だけを対象にする、と明文化しコードに落とす。 ```python # 擬似コード: スコープの明文化 def get_relevant_text(transcript): last_user_idx = max(i for i, m in enumerate(transcript) if m.role == "user") # 最後のユーザー発言の直後から現在まで return transcript[last_user_idx + 1:] ``` --- ## 型3: 配布が消える(ローカルに置いた≠効いている) ### 症状 共通ルール置き場が `git clone` ではなく zip 展開等で丸ごと置き換わる運用だと、ローカルに置いた hook 本体が次回同期で消える。 その結果、設定ファイル側の登録だけが残り、存在しないファイルを呼ぶ状態になる。hook は fail-open 設計が定石のため、エラーにならず誰も気付かない。 ### 直し方 **正本リポジトリに入るまで「完了」と言わない。** 保護ブランチなら PR とマージが要る。ローカルで `chmod +x` やパス設定をしても、それは一時的な効力に過ぎない。 --- ## 検証: 契約テストを書く(単体テストでは足りない) hook の契約は:「stdin に JSON → stdout に1行 JSON、例外は握って exit 0」。テストもこの契約単位で書く。 ### 最低5ケース 1. **不備のある依頼** → block 2. **完全な手順** → pass 3. **ループ防止フラグが立っていたら** → 常に pass(hook 自身が再起動しないため) 4. **壊れた入力** → exit 0(fail-open の確認) 5. **実際に誤爆した本物の応答**を固定データにした回帰テスト ### テスト種別とカバレッジ | テスト種別 | 捕まえられる型 | 捕まえられない型 | |---|---|---| | judge 関数の単体テスト | 型1(判定ロジックの誤り) | 型2(スコープバグ)、型3(配布消滅) | | 契約テスト(stdin→stdout) | 型1、型2(入力の作り方次第) | 型3 | | 実データ回帰テスト | 型1(特に誤爆の再発) | 型2、型3 | | 配布確認テスト | 型3のみ | 型1、型2 | 回帰テストは「実際に止まった応答の全文」をそのまま固定データにするのが最も効く。「止まった理由」を考えて短く整形したデータでは、誤爆の微妙な文脈が失われる。 ```bash # 契約テストの例(fail-open 確認も含む) echo '{"invalid json"' | ./check_hook # 期待: exit code 0、処理継続 ``` --- ## 配布後の確認手順(3行) 1. **正本に入ったか:** コミット/PR番号で確認する。 2. **ローカルの当該ファイルをわざと削除 → 同期を実行 → 復活するか。** 復活すれば正本に入っている証拠。消えたままなら、ローカル直置きでしか存在していない。 3. **誤爆の回帰と、不備の検知の両方を再実行する。** 片方だけ通しても意味がない。 --- ## まとめ fail-open は正しい設計だが、「静かに無効化される」ことと表裏一体。ファイルが存在し、実行権限があり、最新版であることを確認する死活監視は、hook 本体とは別の仕組みで測る必要がある。 また、hook の動作確認だけに時間をかけず、「入力をどう切り出すか」と「デプロイで消えないか」を常に検証対象に含めること。この2つは判定ロジックのバグではなく、テストで「書くべきものが抜けている」ために検出されない。 作った直後に一度だけ「消して・同期して・戻るか」を確かめておけば、静かな無効化は防げる。 ---