【ITニュース解説】Cómo evitar que Claude Code borre tu proyecto: hooks de seguridad en 5 minutos

近年、AI（人工知能）がコードの生成やデバッグ、さらにはプロジェクト管理までこなす「AIコードエージェント」が登場し、開発作業を劇的に効率化している。これらのAIは、プログラマーの指示に基づいて自動的にコマンドを実行したり、ファイルを作成・編集したりするため、非常に強力なツールとなる。しかし、その強力さゆえに、AIが意図せずプロジェクトに深刻なダメージを与える危険性も潜んでいる。例えば、誤って開発中の大切なコードをすべて消してしまう git reset --hard のようなコマンドを実行してしまえば、それまでの作業が無駄になりかねない。このような破壊的な操作からプロジェクトを守るために、「フック」という重要な仕組みがある。

フックとは、Claude CodeのようなAIが特定の動作をする「前」や「後」に、あらかじめ用意しておいたスクリプト（小さなプログラム）を自動的に実行させる機能だ。これは、ソフトウェア開発における「イベント駆動型プログラミング」の考え方に近い。AIが何かツール（例えば、コマンドラインツール）を使おうとするとき、その直前にフックが発動し、AIの行動を監視・制御できるのである。特に「PreToolUse」フックは、AIがツールを使用する直前に起動するため、問題のある操作を未然に防ぐ上で非常に重要だ。このPreToolUseフックが実行され、もしそのスクリプトが「終了コード2」という特別な値を返すと、AIの現在の行動は即座にキャンセルされる。同時に、フックから返されたエラーメッセージがAI自身に伝えられ、AIはそのメッセージを元に自分の計画を修正するよう促される。これにより、AIが危険なコマンドを実行する前に停止させ、より安全な代替案を考えさせることが可能になる。

具体的なフックの活用例として、まず一つ目は「破壊的コマンドのブロック」が挙げられる。これは、プロジェクトにとって致命的な損害を与えかねないコマンドの実行を阻止するためのフックだ。例えば、LinuxやmacOSでファイルやディレクトリを強制的に削除する rm -rf ~（ユーザーのホームディレクトリを削除）や rm -rf /（システム全体を削除）、バージョン管理システムGitで過去のコミット履歴を強制的に上書きする git push --force、あるいはコミットしていない変更をすべて破棄する git reset --hard などがこれにあたる。さらに、インターネット上からスクリプトをダウンロードしてそのまま実行する curl | sh のようなコマンドも、セキュリティ上のリスクが高い。

このフックはPythonで書かれたスクリプトであり、AIが実行しようとするコマンドの文字列を受け取り、あらかじめ定義された危険なコマンドパターンと照合する。この照合には「正規表現」という特別なパターンマッチングの記法が使われる。正規表現を使うことで、例えば rm コマンドの後に -rf のようなオプションが続き、その後に ~ や / といった危険なパスが続くパターンを柔軟に検知できるのだ。もしAIが実行しようとしたコマンドがこれらの危険なパターンに一致した場合、スクリプトはコンソールに「ブロックされた理由」を示すエラーメッセージを表示し、そして「終了コード2」を返してAIの行動を停止させる。

二つ目のフックの例は、「機密ファイルの読み取り防止」だ。開発プロジェクトでは、データベースのパスワード、APIキー、秘密鍵など、外部に漏れてはならない重要な情報がファイルに保存されていることがよくある。例えば、.env ファイルには環境変数が、*.pem や id_rsa ファイルには証明書やSSHの秘密鍵が格納されていることが多い。もしAIがこれらの機密ファイルを誤って読み取り、その内容を外部に送信したり、不適切な場所に書き込んだりすれば、深刻なセキュリティ事故につながる可能性がある。

このフックも同様にPythonスクリプトで実装され、AIが「ファイルを読み込む」「編集する」「書き込む」といった操作を試みる際に、その対象となるファイルパスを監視する。そして、もし対象ファイルが .env や *.pem、id_rsa といった機密情報を含む可能性のあるファイル名パターンに一致した場合、フックはAIの操作をブロックする。ただし、設定例を示す .env.example のようなファイルは安全であるため、これらはブロックの対象外とするように例外ルールを設けることもできる。これにより、AIはプロジェクトのコードを自由に操作しつつも、機密情報には触れることができなくなり、安全性が向上する。

これらのフックスクリプトを作成したら、Claude Codeがそれらをいつ、どのように利用するかを設定する必要がある。そのための設定ファイルが、プロジェクトルートの .claude/settings.json だ。このJSON形式の設定ファイル内で、"hooks" の項目にフックの情報を記述する。例えば、"PreToolUse" というキーの下に、フックの種類と実行方法を指定する。先に紹介した破壊的コマンドをブロックするフックの場合、"matcher": "Bash" と設定することで、Claude CodeがBashコマンドを実行しようとするときにのみ、そのフックが起動するように限定できる。そして、"hooks" の配列内に、"command" タイプとしてPythonスクリプトへのパスを指定する。このパスは、"$CLAUDE_PROJECT_DIR" という環境変数を使って、プロジェクトのルートディレクトリからの相対パスで指定できるため、環境に依存せず柔軟に設定できる。設定が完了したら、Claude Codeを一度再起動し、Claude Codeのインターフェースで /hooks コマンドを実行して、設定したフックが正しくアクティブになっているか確認することが重要だ。

フックが正しく動作するかどうかを、実際に危険なコマンドを実行することなく安全にテストする方法もある。例えば、破壊的コマンドをブロックするPythonスクリプトに、手動で擬似的な入力を与えて実行してみるのだ。コマンドラインで echo '{"tool_input":{"command":"rm -rf ~"}}' | python3 .claude/hooks/bloquear.py のように実行し、その直後に echo $? と入力してスクリプトの終了コードを確認する。もしフックが期待通りに動作していれば、危険なコマンドに対しては終了コード「2」が返り、安全なコマンド（例えば npm test）に対しては終了コード「0」が返るはずだ。このようにして、本番環境に影響を与えることなく、フックの挙動を検証できる。

このように、AIコードエージェントの「フック」機能は、AIの強力な自動化能力を最大限に活用しつつも、潜在的なリスクからプロジェクトを確実に保護するための非常に効果的なメカニズムだ。システムエンジニアを目指す初心者にとっても、AIを安全かつ効率的に開発プロセスに組み込むためのこのような安全対策の知識は、これからのAI時代において不可欠なスキルとなるだろう。AIとの協調作業が当たり前になる未来において、AIの能力を信頼しつつも、適切なガードレールを設けることが、より堅牢で安全なソフトウェア開発を実現する鍵となる。