Claude Code Guardrails Kit

Claude Code 運用で実際に発生した事故・未遂事故の教訓をもとに構築した、 汎用ガードレール集です。

KA（Knowledge Assistant）内部での実運用から抽出したルールとHooksセットを、 KA固有の依存（RAG・SQLite・独自MCP）を除去して汎用化しました。

---

免責事項

本ガードレールキットは「現状のまま（AS IS）」で提供されます。 作者は本キットの使用によって生じたいかなる損害・損失についても責任を負いません。

ご利用にあたっての注意事項：

• 本キットはあくまで補助ツールです。 Claude Code の動作を完全にコントロールするものではありません
• settings.json の編集は必ずバックアップ後に行ってください。 既存設定の上書きによるサービス影響を防ぐためです
• Hooks スクリプトはユーザーの環境で直接実行されます。 内容を理解した上で導入してください
• セキュリティの保証はしません。 本キットはセキュリティの向上を目的としていますが、万全な保護を保証するものではありません
• Claude Code のバージョンアップにより動作が変わる場合があります。 定期的に動作確認をしてください

---

全体アーキテクチャ

graph TD
    subgraph "Claude Code 制御の3層"
        A["CLAUDE.md（ガイドライン）<br/>LLMへの指示・行動指針"]
        B["Hooks（ガードレール）<br/>システム的強制・自動実行"]
        C["rules/*.md（詳細ルール）<br/>条件付き注入・外出し定義"]
    end

    A --> |"常時読込、ただし保証なし"| LLM["Claude LLM"]
    B --> |"イベント発火で必ず実行"| LLM
    C --> |"prompt-guard.sh が検索してオンデマンド注入"| LLM

    subgraph "Hooks イベントライン"
        E1["SessionStart<br/>session-start.sh"]
        E2["UserPromptSubmit<br/>prompt-guard.sh"]
        E3["PreToolUse<br/>explain-risk.js"]
        E4["PostToolUse<br/>（プロジェクト固有）"]
        E5["Stop<br/>commit-reminder.sh"]
    end

Loading

---

構成

claude-rules/
├── README.md                    ← このファイル
│
├── global/                      ← 全プロジェクト共通（~/.claude/ に展開）
│   ├── CLAUDE.md                ← ~/.claude/CLAUDE.md に追記するグローバルルール
│   └── .claude/
│       └── rules/               ← ~/.claude/rules/ に展開
│           ├── bash-timeout.md      ← 長時間コマンドのタイムアウト対策
│           └── config-change.md     ← 設定ファイル変更前の確認手順（paths: フィルタ付き）
│
├── project/                     ← プロジェクト固有（PROJECT_ROOT/ に展開）
│   ├── CLAUDE.md                ← PROJECT/CLAUDE.md に追記するプロジェクトルール
│   ├── .claude/
│   │   └── rules/               ← PROJECT/.claude/rules/ に展開
│   │       ├── git-workflow.md      ← Gitflowルール詳細（prompt-guard.sh が自動注入）
│   │       └── destructive-ops.md  ← 破壊的操作の確認手順（prompt-guard.sh が自動注入）
│   └── hooks/                   ← プロジェクト固有Hookの定義例
│       ├── python-quality-gate.sh  ← Python (.py) 編集後の ruff 自動チェック
│       └── settings.json           ← プロジェクト固有設定の定義例（.claude/settings.json に置く）
│
└── hooks/                       ← グローバルHook（~/.claude/hooks/ に展開）
    ├── README.md                    ← Hooks 設置手順
    ├── settings.template.json       ← ~/.claude/settings.json のテンプレート
    ├── session-start.sh             ← SessionStart: 共通コンテキスト注入（キャッシュ有効）
    ├── prompt-guard.sh              ← UserPromptSubmit: キーワード別ルール注入
    ├── explain-risk.js              ← PreToolUse: 破壊的操作のリスク可視化（Node.js）
    └── commit-reminder.sh           ← Stop: 未コミット変更の検知・警告

---

考え方: 3層の使い分け

種別	役割	保証レベル	ファイル
CLAUDE.md	行動ガイドライン（LLMへの指示）	守られることが多いが構造的保証なし	global/CLAUDE.md, project/CLAUDE.md
rules/*.md	詳細ルールの外出し（条件付き注入）	prompt-guard.sh 経由で必要な時だけ注入	global/.claude/rules/, project/.claude/rules/
Hooks	ガードレール（システム的強制）	LLMが「忘れても」必ず実行される	hooks/, project/hooks/

CLAUDE.md だけでは足りない。3層を組み合わせて初めて機能する。

CLAUDE.md を短く保つ理由

CLAUDE.md は毎回全量をコンテキストに読み込む。長いほど LLM の推論精度が下がる。 詳細なルールは rules/ に外出しし、prompt-guard.sh で必要なときだけ注入する。

---

Hooks スコープ: global vs project

graph LR
    subgraph "グローバル（~/.claude/settings.json）"
        G1["session-start.sh<br/>SessionStart"]
        G2["prompt-guard.sh<br/>UserPromptSubmit"]
        G3["explain-risk.js<br/>PreToolUse"]
        G4["commit-reminder.sh<br/>Stop"]
    end

    subgraph "プロジェクト固有（.claude/settings.json）"
        P1["python-quality-gate.sh<br/>PostToolUse"]
        P2["（例）node-lint-gate.sh<br/>PostToolUse"]
        P3["（例）go-vet-gate.sh<br/>PostToolUse"]
    end

    G1 --> |"全プロジェクトに適用"| ALL["すべてのプロジェクト"]
    P1 --> |"そのプロジェクトのみ"| PY["Python プロジェクト"]
    P2 --> |"そのプロジェクトのみ"| NODE["Node.js プロジェクト"]
    P3 --> |"そのプロジェクトのみ"| GO["Go プロジェクト"]

Loading

言語固有の品質ゲートはプロジェクトごとに PROJECT_ROOT/.claude/settings.json で定義する。 project/hooks/ の settings.json を参考に、言語に合わせて書き換える。

---

クイックスタート

1. グローバル Hooks の設置（全員共通）

# 作業ディレクトリに移動
cd /path/to/this/repo

# ホームディレクトリのパスを確認
echo $HOME

# ~/.claude/hooks/ に 4 本のスクリプトをコピー
mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
cp hooks/*.js ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# ~/.claude/rules/ にグローバルルールをコピー
mkdir -p ~/.claude/rules
cp global/.claude/rules/*.md ~/.claude/rules/

2. settings.json の設定

hooks/settings.template.json を参考に ~/.claude/settings.json を作成・更新する。 既存の settings.json がある場合は必ずバックアップ後にマージすること。上書き厳禁。

# テンプレートをコピー（既存がない場合のみ）
cp hooks/settings.template.json ~/.claude/settings.json

# パスを実際のホームディレクトリに置き換える
sed -i "s|/path/to/home|$HOME|g" ~/.claude/settings.json

詳細は hooks/README.md を参照。

3. CLAUDE.md のルール追記

# グローバルルールを ~/.claude/CLAUDE.md に追記
cat global/CLAUDE.md >> ~/.claude/CLAUDE.md

4. プロジェクトルールの展開（任意）

# プロジェクトルートで実行
cd /path/to/your-project

# プロジェクト固有ルールをコピー
mkdir -p .claude/rules
cp /path/to/claude-rules/project/.claude/rules/*.md .claude/rules/

# CLAUDE.md に追記
cat /path/to/claude-rules/project/CLAUDE.md >> ./CLAUDE.md

5. 言語別品質ゲートの設置（任意）

Python プロジェクトの場合:

cd /path/to/your-python-project

# スクリプトをコピー
mkdir -p .claude/hooks
cp /path/to/claude-rules/project/hooks/python-quality-gate.sh .claude/hooks/
chmod +x .claude/hooks/python-quality-gate.sh

# settings.json を作成（project/hooks/settings.json を参考に）
cp /path/to/claude-rules/project/hooks/settings.json .claude/settings.json
# .claude/settings.json 内の /path/to/project を実際のパスに置き換える
sed -i "s|/path/to/project|$(pwd)|g" .claude/settings.json

他言語への応用は project/hooks/settings.json の _comment セクションを参照。

---

優先度ガイド

導入効果が高い順:

優先度	種別	対象	防ぐもの
★★★	settings.json deny	全員	認証情報（.credentials.json・SSH鍵）の読み取り・漏洩
★★★	commit-reminder.sh	全員	セッション終了時のコミット忘れ
★★☆	explain-risk.js	全員	rm -rf・git push --force 等の破壊的操作の見落とし
★★☆	session-start.sh	全員	基本ルールの未注入（キャッシュ有効・コスト低）
★★☆	prompt-guard.sh	全員	GitルールやDB操作ルールの「指示し忘れ」
★☆☆	python-quality-gate.sh	Python PJ	ruff エラーの放置・後回し
★☆☆	global/.claude/rules/bash-timeout.md	全員	docker build 等のタイムアウト事故
★☆☆	global/.claude/rules/config-change.md	全員	設定ファイルの意図しない上書き・リセット

---

著者の関連記事

本キットの背景・設計思想・活用事例について、以下の記事で解説しています。

Zenn

• Claude Codeカスタマイズエコシステムの全体像
• Claude Code Hooks 実践ガイド
• Claude Code × エージェントチームで変わる開発体験

Qiita

• Claude Codeのカスタマイズで変わったこと
• Claude CodeのHooksで作るガードレール
• CLAUDE.mdとrulesで実現するコンテキスト制御
• Claude Codeエージェントチームの構築と運用