🚨 ペインポイント：Claude Codeの「危険な瞬間」

Vibe Codingをしていて、こんなイライラする場面に遭遇したことはありませんか？

❌ mainブランチへの直接変更 → 一つのミスで重要なコードが上書きされる
❌ 中断された変更 → 中間成果物が失われ、特定の状態にロールバックできない
❌ 混沌とした複数の変更 → どの変更がバグを引き起こしたのか分からない
❌ 重要なファイルを誤って削除 → タイムリーなコミットがなく、ゲームオーバー
❌ 手動変更の上書き → AIがコミットされていない手動変更を直接上書き、コードの所有権を区別できない

💡 解決策：Claude Code ガードレール

Claude Code Hookに基づくガードレール

3重セキュリティメカニズム: 🛡️ 書き込み前の遮断アラート + 📸 精密なスナップショットコミット + 🔄 スマートマージアーカイブ

✅ 保護ブランチの遮断 → mainブランチへの書き込みを自動的にブロック、フィーチャーブランチの作成を提案
✅ コミットされていない変更の保護 → 手動変更がコミットされていない場合はブロック、上書きを避けるため先にコミットを強制
✅ ファイルレベルの精密なスナップショット → 各変更で変更されたファイルのみをコミット、ノイズを回避
✅ スマートバックアップメカニズム → gitignoreファイル変更前の自動バックアップ
✅ 安全な履歴マージ → 複数のチェックポイントをクリーンなタスクコミットにインテリジェントにマージ

✨ コア機能

🔧 完璧な互換性

• ✅ 既存のClaude Code Hooksを上書きしない - .claude/settings.jsonをインテリジェントにマージ
• ✅ バックアップ + 重複排除 + 冪等性 - 複数インストールでも安全
• ✅ ユーザーフックと共存 - 既存のワークフローに影響しない

🆚 他のソリューションとの比較

🧰 前提条件

• Git がインストールされ初期化されている（user.name / user.emailが設定済み）

• Claude Code がインストールされている（HooksとPreToolUse exit=2ブロッキングをサポートするバージョン）

• jq（Hook入力JSONを解析するため）

  • macOS: brew install jq
  • Ubuntu: sudo apt-get install -y jq

🚀 クイックスタート

# プロジェクトレベルのインストール
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/install.sh | bash

# グローバルインストール
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/install.sh | bash -s -- --global

cp -r .claude/ /path/to/your-project/
chmod +x /path/to/your-project/.claude/hooks/guardrails/*.sh

🗑️ アンインストール

# プロジェクトレベルのアンインストール
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/uninstall.sh | bash

# スクリプトファイルを保持、settings.jsonからのみ削除
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/uninstall.sh | bash -s -- --keep-scripts

# グローバルアンインストール
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/uninstall.sh | bash -s -- --global

🗂️ ディレクトリ構造

.
├─ .claude/
│  ├─ settings.json                 # Hookエントリーとマッチングルール（テンプレート）
│  └─ hooks/
│     ├─ guardrails/
│     │  ├─ guard-branch.sh         # 書き込み前ブランチガード（保護ブランチブロッキング）
│     │  ├─ auto-commit.sh          # 変更ごとの精密スナップショットコミット
│     │  └─ squash-checkpoints.sh   # Stop/Compactステージの安全なマージ
├─ install.sh                       # ワンクリックインストール（マージ/バックアップ/重複排除/冪等性）
├─ uninstall.sh                     # ワンクリックアンインストール（スクリプト保持可能）
├─ README.md
├─ LICENSE                          # MIT

📺 効果のデモ

graph LR
    A[🔄 Claude Codeが書き込みを試行] --> B{🛡️ ブランチチェック}
    B -->|保護ブランチ| C[❌ ブロックしてアラート]
    C --> D[💡 vibeブランチの作成を提案]
    B -->|安全なブランチ| E{📝 コミットされていないチェック}
    E -->|コミットされていない| F[❌ 先にコミットを強制]
    F --> G[💾 手動変更の保存を促す]
    E -->|コミットされていない変更なし| H[✅ 書き込みを許可]
    H --> I[📸 自動チェックポイント]
    I --> J[💾 変更されたファイルを正確にコミット]
    J --> K[🔚 セッション終了]
    K --> L[📦 タスクコミットにスマートマージ]
    
    style B fill:#ff9999
    style E fill:#ffcc99
    style I fill:#99ff99
    style L fill:#9999ff

🧪 使用例

シナリオ1：保護ブランチの遮断

保護ブランチで書き込みを試行 → ブロックしてアラート、ターミナルがvibeブランチの作成を提案：

⚠️  Branch 'main' is protected.
   Current branch 'main' is protected.

It's recommended to create/switch to a vibe branch before making changes:
建议创建/切换到 vibe 分支再修改，例如：
  git checkout -b vibe/20250811142530-claude

シナリオ2：コミットされていない変更の保護

コミットされていない手動変更を検出 → ブロックして先にコミットを促す：

⚠️  Detected uncommitted changes in the repository.
   检测到仓库中有未提交的更改。

There are uncommitted changes that may be lost if AI overwrites them.
存在未提交的更改，如果被 AI 覆盖可能导致代码丢失。

Consider committing these changes first:
建议先提交这些更改：
  git add .
  git commit -m "Save work in progress"

シナリオ3：通常のワークフロー

vibeブランチに切り替えて作業を継続 → 各Write/Edit/MultiEdit後に自動チェックポイント：

checkpoint: Write src/LoginForm.tsx - 14:25
checkpoint: Edit src/types.ts - 14:26

gitignoreファイルを変更する場合、バックアップリマインダーを受け取ります：

📦 Backup Notice: '.env' is a gitignored file. A backup has been saved to '.claude/backups/.env.20250811-142530' before claude code modification.
📦 备份提醒: '.env' 是 gitignore 文件，claude code 修改前已备份到 '.claude/backups/.env.20250811-142530'

シナリオ4：セッション終了の整理

セッション終了stop / compactトリガー → 複数のチェックポイントを自動的に1つのタスクコミットにマージ：

task: modify LoginForm.tsx, types.ts - 2025-08-11

🛡️ セキュリティ戦略とベストプラクティス

• ブランチ保護: デフォルトでmain|master|dev|release*を保護、guard-branch.shで調整可能。
• 公開履歴を壊さない: 保護ブランチではスカッシュしない；「アップストリームなしまたはahead>0」の場合のみチェックポイントをマージ。
• コラボレーション推奨: リモートブランチ保護（強制プッシュなし/PR必須）と組み合わせるとより安定。

🔧 カスタマイズガイド

• コミットメッセージ規則: auto-commit.shをchore(checkpoint): ...に変更；Stopステージはvibe/fix/...タイプを出力（Conventional Commits）。
• より厳格な書き込みパス: 「直接ファイル書き込みツール」を完全に防ぐには、PreToolUseでカスタムMCP書き込みツールのみを許可し、汎用的なWrite|Edit|MultiEditをブロック。
• 外部統合: PostToolUseまたはStopでCLI/APIを呼び出す（チケット、PR、メッセージ通知など）。

❓ よくある質問（FAQ）

Q: 既存のフックを上書きしますか？

A: いいえ。インストールスクリプトはjqを使用して.claude/settings.jsonをマージし、同じmatcherに対して追加と重複排除のみを行います；書き戻す前に.bak.*バックアップを生成します。

Q: 手動でコードを変更したがまだコミットしていない場合、Claude Codeは作業を続けることができますか？

A: いいえ。guard-branch.shはコミットされていない変更を検出して操作をブロックし、先にコミットするよう促します。これにより、AIが手動変更を上書きすることを防ぎ、コードの所有権が明確で追跡可能になります。

Q: 複数のフックは順番に実行されますか？

A: 同じイベントにマッチする複数のフックは並列で実行されます；厳密な順序が必要な場合は、同じスクリプトに複数のコマンドを記述してシリアル実行します。

Q: Windowsをサポートしていますか？

A: スクリプトはPOSIXシェルベースです。WindowsユーザーはWSLまたはUnix系環境の使用を推奨します。

🌟 コミュニティサポート

📄 ライセンス