Posted inAI

Claude Codeの自動化：フックを使用してAIをローカル環境と同期させる

AI tutorial - IT technology blog
AI tutorial - IT technology blog

問題点：AIツールに文脈の認識が不足している場合

Claude Codeはロジックのリファクタリングが非常に高速ですが、コードが動作しなければその速さに意味はありません。開発者がよく直面する壁があります。Claudeがpackage.jsonに新しい依存関係を追加したのに、ローカル環境が古いままという状況です。結局、「Module not found」エラーを解消するためだけに、手動でnpm installを実行して2〜3分を無駄にすることになります。

これにより、ストレスの溜まるループが生じます。AIにバグ修正を依頼し、AIがコードを書きますが、マイグレーションの不足やロックファイルの不整合のためにテストが失敗します。このような手動のオーバーヘッドは、そもそもCLIツールを使用することで得られる効率性を損なってしまいます。

根本的な原因：意図と環境のギャップ

問題は、Claude Codeが特定の技術スタックのライフサイクルを自動的に理解することなく、ファイルシステム上で動作することにあります。Claudeは構文は見えますが、状態を見逃します。.pyファイルを変更するたびにruffによるチェックが必要であることや、データベースの読み取りにアクティブなSSHトンネルが必要であることまでは把握していません。

フックはこのギャップを埋める役割を果たします。フックがなければ、単に高性能なテキストエディタを使っているに過ぎません。フックを活用することで、AIはパイプラインの機能的な一部となります。フックを使いこなせるかどうかが、AIを「試している」段階と、絶え間ない手動操作なしに実際に機能を「デリバリーしている」段階の分かれ目となります。

インストールとセットアップ

最新バージョンのClaude Code CLIを実行していることを確認してください。まだ開始していない場合は、npm経由でインストールし、アカウントを認証します。

npm install -g @anthropic-ai/claude-code
claude auth login

プロジェクトのルートディレクトリに移動します。個別のフラグを渡すこともできますが、設定ファイルを通じてフックを管理する方が、チーム環境においてははるかに持続可能です。

ライフサイクルフックの設定

Claude Codeでは、特定の実行ポイントでスクリプトをトリガーできます。これらは.claudecode.jsonファイルに記述します。主に2つのタイプに焦点を当てます。pre-tool（Claudeがeditやgrepなどを使用する前に実行）と、post-tool（ツールがタスクを完了した後に実行）です。

1. 依存関係チェックの自動化 (Pre-Tool)

Claudeがテストを実行したりスクリプトを動かしたりする前に、環境が最新であることを確認することをお勧めします。簡単なドライランチェックを行うだけで、回避可能なビルド失敗を何度も防ぐことができます。

以下を.claudecode.jsonに追加します：

{
  "hooks": {
    "pre-tool": "npm install --dry-run | grep 'up to date' || npm install"
  }
}

これで、Claudeがツール呼び出しを準備するたびに、Nodeモジュールが検証されます。これにより、ローカルパッケージの不足によってAIが「幽霊バグ」を追いかけるのを防ぐことができます。

2. コード品質の強制 (Post-Tool)

自動フォーマットは、Gitの履歴を綺麗に保つための最も効果的な方法です。Claudeがファイルを編集した場合、そのファイルを即座にフォーマットしたいはずです。これにより、後で「lint修正」という煩わしいコミットを作成する必要がなくなります。

{
  "hooks": {
    "post-tool": "if [ \"$CLAUDE_TOOL_NAME\" = \"edit_file\" ]; then npx prettier --write $CLAUDE_LAST_MODIFIED_FILE; fi"
  }
}

Claudeは$CLAUDE_TOOL_NAMEや$CLAUDE_LAST_MODIFIED_FILEといった環境変数を提供しています。これらを使用してスクリプトを正確にターゲットすることで、1行の変更のためにプロジェクト全体を再フォーマットすることを避けることができます。

実践例：Pythonのワークフロー

以下は、Python開発者向けの堅牢な設定例です。ツールの実行前に仮想環境を有効化し、編集直後にpytestを実行してロジックを検証します。

{
  "hooks": {
    "pre-tool": "source venv/bin/activate",
    "post-tool": "if [[ \"$CLAUDE_TOOL_NAME\" == *\"edit\"* ]]; then pytest tests/unit_tests.py; fi"
  }
}

ツール名に「edit」が含まれている場合のみにフィルタリングすることで、Claudeがディレクトリ構造を確認するために単にlsを使用しているときに、テストスイート全体が実行されるのを防ぐことができます。

検証 and モニタリング

フックが有効になると、Claude Codeはそのステータスをターミナルに直接表示します。pre-toolフックが0以外の終了コードを返した場合、Claudeは直ちに停止します。この安全メカニズムにより、壊れた環境に基づいてAIが変更を加えるのを防ぎます。

失敗したフックのデバッグ

スクリプトが正しく実行されない場合は、出力を隠しログファイルにリダイレクトしてください。これにより、メインのターミナルを綺麗に保ちながら、トラブルシューティングを行う場所を確保できます。

{
  "hooks": {
    "post-tool": "./scripts/check-env.sh >> .claude_hook_debug.log 2>&1"
  }
}

パフォーマンスに関する考慮事項

フックは高速である必要があります。もしpost-toolスクリプトが10分かかる統合テストスイートを実行してしまうと、AIワークフローは加速装置ではなくボトルネックになってしまいます。フィードバックループを短く保つための工夫をしましょう：

  • フルエンドツーエンドテストの代わりに、フェイルファストなリンターを使用する。
  • チェックを$CLAUDE_LAST_MODIFIED_FILEに限定する。
  • 重いロギングやテレメトリはバックグラウンドプロセスにオフロードする。

ベストプラクティスのまとめ

自動化の信頼性を維持するために、次の3つのルールに従ってください：

  1. べき等性 (Idempotency): スクリプトを複数回実行しても安全である必要があります。npm installは安全ですが、git commitは空のコミットを避けるための追加のロジックが必要です。
  2. 特定性 (Specificity): 環境変数を使用して、AIが実際にコードを変更したときにのみスクリプトが実行されるようにします。
  3. 静音性 (Silence): フックの出力は最小限に抑えてください。過剰なログはAIのコンテキストウィンドウを圧迫し、本当のエラーを見つけるのを難しくします。

これらのガードレールを設置することで、Claudeが生成するコードが常にローカル環境の実態に即したものになります。

Share:
Tags: