CLAUDE.mdにNEVER delete files in productionと書いたのに、長い作業の後半で守られなかった——Claude Codeを運用していると、必ずこの局面が来ます。

この記事では、なぜCLAUDE.mdのルールが「抜ける」のかの構造的な理由と、hookがなぜ確実に動くのかを整理します。

環境

Claude Code（hooks対応バージョン）
CLAUDE.md運用（4,696文字・115行規模）
UserPromptSubmit / Stop / PreCompact hookを本番運用中

結論：ソフトウォールとハードウォールの違い

仕組み	どう機能するか	信頼性
CLAUDE.mdのルール記述	LLMがコンテキストとして読む → 確率的に従う	ソフトウォール（コンテキストが長くなると抜けやすい）
hook（UserPromptSubmit/Stop等）	Claude Codeハーネスが実行する → 必ず動く	ハードウォール（LLMの判断と独立）

CLAUDE.mdは「してほしいこと」の定義場所。hookは「必ずさせること」の実装場所。

なぜCLAUDE.mdは「ソフトウォール」なのか

CLAUDE.mdに書いたルールは、Claudeへのコンテキスト注入として機能します。LLMはそれを読み、「できる限り従おうとします」が、以下の条件で崩れます。

コンテキストウィンドウが長くなる: 会話が長くなるにつれ、CLAUDE.mdの内容が相対的に薄まります。直近の会話の方がLLMにとって重い文脈になります。

ルールの量が多い: 禁止事項が増えると、多数の判断が必要な場面で一部が見落とされやすくなります。

強調語の効力消失: NEVER、MUST NOT、CRITICALを多用すると、すべての記述が同じ重みになります。

なぜhookは「ハードウォール」なのか

hookはClaude Codeのハーネスが、定義されたライフサイクルポイントで実行します。Claudeのコンテキストに依存しません。

// settings.json の例
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/git-status-check.sh"
          }
        ]
      }
    ]
  }
}

このスクリプトは、Claudeが「実行するかどうか判断する」のではなく、ハーネスが強制的に呼び出します。LLMの判断が介在しません。

さらに、settings.jsonを編集するとhot reloadが効き、同じセッション内で即座に反映されます（「次セッションから有効」ではない）。

CLAUDE.mdに書くこと vs hookに移すこと

CLAUDE.mdに書く（LLMへのコンテキスト定義）

プロジェクトの文脈定義（ターゲット・方針）
高レベルのアーキテクチャ方針
役割とスコープ
推奨パターン

hookに移す（「必ず起こさなければならないこと」）

タイミング	hook種別	用途の例
毎プロンプト前	UserPromptSubmit	git contextの自動注入、lintチェック
作業完了後	Stop	git statusの可視化、未pushの警告
コンテキスト圧縮前	PreCompact	状態スナップショットの保存

判断の基準: 「1回でも抜けたら困るルール」は全部hookへ移す。

# Stop hookの例（git-status-check.sh）
#!/bin/bash
STATUS=$(git status --short)
UNTRACKED=$(git ls-files --others --exclude-standard | wc -l)

if [ -n "$STATUS" ] || [ "$UNTRACKED" -gt 5 ]; then
  echo "⚠️  作業後の状態確認"
  echo "変更: $(echo "$STATUS" | wc -l)件 / untracked: ${UNTRACKED}件"
  git status --short | head -20
fi

まとめ

CLAUDE.mdのルールが守られない原因は「書き方の問題」ではなく「仕組みの問題」です。hookを設計に組み込むことで、「また守られなかった」のループから抜け出せます。

AI ツールを業務に組み込む設計の実験ログを書いています。 https://masatoman.net