ルール強制 hook が本番で壊れる3つの型と検証方法

運用ルール強制 hook が本番で壊れる3つの型と、その検証方法

前提: 「ルール文を足しても守られない。守らせたいなら実行を機械的に止める(Stop hook)」という設計は既知。この記事は「作った後に必ず起きる壊れ方」を扱う。

---

型1: 部分一致による誤爆(言及と実行を区別できない)

症状

禁止語・トリガー語を本文に部分一致でgrepすると、「その語について説明している文」まで検知して止まる。

実例: 手作業依頼を検出する hook が、自分の完了報告——「手作業を頼む前に検証する、と記録した」——で発火し、応答が出せなくなった。

さらに悪化するパターンは、表・引用・コードブロックの中に手順例を貼っただけで発火するケース。ユーザーが「例えばこの禁止行為をやったらどうなる?」と質問しただけでも止まる。

直し方

• (a) トリガーは「依頼の言い回し」だけに絞る。判定語を許可する。単語単位ではなく、命令形+人称のパターンで検知する(例:「〜してください」「押してください」)。
• (b) 判定対象からコードフェンス・引用・表を除去してから評価する。
• (c) 過去の話法(「〜と記録した」「〜だった」「〜と書いた」)を除外する。

# 擬似コード: トリガー判定の絞り込み
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)の単体テストでは絶対に出ない。入力を人が作るから。判定関数は「渡された文字列」に対してだけ正しく動き、「どの文字列を渡すか」の範囲選択ロジックのバグは、統合テストまで表面化しない。

直し方

「最後のユーザー発言より後ろ」だけを対象にする、と明文化しコードに落とす。

# 擬似コード: スコープの明文化
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

回帰テストは「実際に止まった応答の全文」をそのまま固定データにするのが最も効く。「止まった理由」を考えて短く整形したデータでは、誤爆の微妙な文脈が失われる。

# 契約テストの例(fail-open 確認も含む)
echo '{"invalid json"' | ./check_hook
# 期待: exit code 0、処理継続

---

配布後の確認手順(3行)

1. 正本に入ったか: コミット/PR番号で確認する。
2. ローカルの当該ファイルをわざと削除 → 同期を実行 → 復活するか。 復活すれば正本に入っている証拠。消えたままなら、ローカル直置きでしか存在していない。
3. 誤爆の回帰と、不備の検知の両方を再実行する。 片方だけ通しても意味がない。

---

まとめ

fail-open は正しい設計だが、「静かに無効化される」ことと表裏一体。ファイルが存在し、実行権限があり、最新版であることを確認する死活監視は、hook 本体とは別の仕組みで測る必要がある。

また、hook の動作確認だけに時間をかけず、「入力をどう切り出すか」と「デプロイで消えないか」を常に検証対象に含めること。この2つは判定ロジックのバグではなく、テストで「書くべきものが抜けている」ために検出されない。

作った直後に一度だけ「消して・同期して・戻るか」を確かめておけば、静かな無効化は防げる。