Skip to content

README_JA.md

Latest commit

 

History

History
467 lines (336 loc) · 16.4 KB

README_JA.md

File metadata and controls

467 lines (336 loc) · 16.4 KB
Raw

🛡️ Claude Code ガードレール

より安全なClaude Code開発のためのスマートガードレールシステム

GitHub Stars GitHub Forks License Issues

🔥 このプロジェクトが役に立ったら、右上の ⭐ スターをクリックして応援してください！

🇺🇸 English | 🇨🇳 中文 | 🇯🇵 日本語

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

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

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

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

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

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

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

🎉 今すぐ体験を開始！

今すぐインストール    スターをクリック

✨ コア機能

🛡️ 二重セキュリティ保護

  • 保護ブランチの遮断
  • コミットされていない変更の検出
  • 書き込み前のブロックアラート
  • vibeブランチ作成のスマート提案
  • 続行前に手動変更の強制コミット

📸 精密なスナップショット

  • ファイルレベルのスナップショットコミット
  • git add .からのノイズを回避
  • 現在変更されたファイルのみをコミット
  • 完全な変更履歴を保持

🔄 スマートバックアップ

  • gitignoreファイルの自動バックアップ
  • 変更前に.claude/backups/にバックアップ
  • バイリンガルのフレンドリーなリマインダー
  • 重要な設定ファイルの損失を防止

📦 履歴の整理

  • 安全なスカッシュマージ
  • 複数のチェックポイントをタスクにマージ
  • 保護ブランチの履歴を壊さない
  • Git履歴をクリーンに保つ

🔧 完璧な互換性

  • ✅ 既存の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

📁 方法2：手動コピー

直感的で透明、完全制御

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

✨ インストールスクリプトの機能

🔄 スマートマージ - 既存の設定を上書きしない
💾 自動バックアップ - 変更前にsettings.jsonをバックアップ
🔁 冪等性の安全性 - 複数実行しても副作用なし
🧹 重複排除 - 重複する設定項目を回避

🗑️ アンインストール

# プロジェクトレベルのアンインストール
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
Loading

🧪 使用例

シナリオ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系環境の使用を推奨します。

🌟 コミュニティサポート

💝 役に立ちましたか？サポートしてください！

このリポジトリにスター    フォークして貢献

⚡ トリプルアクション: スター ⭐ + フォーク 🍴 + シェア 📢

🤝 貢献

🐛 バグを見つけた
Issue提出

💡 機能提案
機能リクエスト

🔀 コード貢献
PR提出

📊 プロジェクト統計

貢献者 最終コミット コミット活動

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細はLICENSEファイルを参照してください

⭐ このプロジェクトが役に立ったら、スターをクリックして応援してください！ ⭐

🛡️ Chase the vibe, but honor the craft. 🛡️