Claude Code を最大限活用する

Hooks とは

Hooks は、Claude Code がツールを実行する前後（またはセッション終了時）に自動的に実行されるスクリプトの仕組みだ。「毎回手動でやっている確認作業」を自動化できる。

3つのフックタイプ

タイプ	実行タイミング	用途
`PreToolUse`	ツール実行の前	バリデーション、パラメータの修正、実行のブロック
`PostToolUse`	ツール実行の後	自動フォーマット、型チェック、警告の出力
`Stop`	セッション終了時	最終確認、監査ログの記録

フックが解決する問題

# フックなし
Claude がコードを編集 → フォーマットが乱れる → 手動で prettier を実行
Claude がファイルを作成 → console.log が残る → 手動で確認
Claude がセッション終了 → 未コミットの変更に気づかない

# フックあり
Claude がコードを編集 → PostToolUse で prettier が自動実行
Claude がファイルを作成 → PostToolUse で console.log を警告
Claude がセッション終了 → Stop で未コミット変更を通知

Hooks導入の効果

項目	hooks なし	hooks あり
コードフォーマット	手動で `prettier` 実行を忘れがち	PostToolUse で編集後に自動フォーマット
型チェック	ビルド時まで型エラーに気づかない	PostToolUse で `.ts` 編集後に即座に `tsc` 実行
セキュリティ	`git push` 前のレビューを忘れる	PreToolUse で push 前にZedエディタでレビューを促す
console.log	本番コードに残留するリスク	Stop hook でセッション終了時に全修正ファイルを監査
ドキュメント生成	不要なREADME等を誤って作成	PreToolUse で不要な `.md` 作成をブロック

基本設定方法

フックは ~/.claude/settings.json（ユーザー全体）または .claude/settings.json（プロジェクト単位）に設定する。

設定ファイルの構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'File modification detected'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "git diff --stat"
          }
        ]
      }
    ]
  }
}

matcher の書き方

matcher にはツール名を正規表現で指定する。

matcher	一致するツール
`"Edit"`	Edit ツールのみ
`"Edit\|Write"`	Edit または Write
`"Bash"`	Bash ツールのみ
`".*"`	全ツール
`""`	全ツール（Stopフック用）

環境変数

フックの実行時には以下の環境変数が利用できる。

変数	内容	例
`$CLAUDE_TOOL_NAME`	実行されたツール名	`Edit`
`$CLAUDE_FILE_PATH`	操作対象のファイルパス	`src/app/page.tsx`

実践例

1. 保存時フォーマット (PostToolUse)

Edit や Write でファイルが変更された後に、自動的に Prettier を実行する。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

ポイント: 2>/dev/null || true を付けると、Prettier がインストールされていない場合でもエラーで止まらない。

2. TypeScript 型チェック (PostToolUse)

TypeScript ファイルが編集された後に tsc --noEmit を実行し、型エラーを検出する。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.ts || \"$CLAUDE_FILE_PATH\" == *.tsx ]]; then npx tsc --noEmit 2>&1 | head -20; fi"
          }
        ]
      }
    ]
  }
}

3. console.log 警告 (PostToolUse)

編集されたファイルに console.log が含まれていないか確認し、あれば警告を出す。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if grep -q 'console\\.log' \"$CLAUDE_FILE_PATH\" 2>/dev/null; then echo 'WARNING: console.log detected in $CLAUDE_FILE_PATH'; fi"
          }
        ]
      }
    ]
  }
}

4. git push 前のレビュー (PreToolUse)

git push の実行前にエディタで変更内容を確認させる。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git push'; then echo 'Review changes before pushing:'; git diff --stat HEAD~1; fi"
          }
        ]
      }
    ]
  }
}

5. セッション終了時の監査 (Stop)

セッション終了時に修正されたファイルの一覧を表示する。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '=== Modified files this session ==='; git diff --name-only 2>/dev/null || echo 'Not a git repository'"
          }
        ]
      }
    ]
  }
}

セキュリティフックの設定

セキュリティに関わる確認を自動化する実践的なフック設定。

機密情報の検出

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if grep -qE '(sk-[a-zA-Z0-9]{20,}|password\\s*=|secret\\s*=|api_key\\s*=)' \"$CLAUDE_FILE_PATH\" 2>/dev/null; then echo 'CRITICAL: Potential secret detected in $CLAUDE_FILE_PATH'; exit 1; fi"
          }
        ]
      }
    ]
  }
}

危険なコマンドのブロック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(rm -rf /|DROP TABLE|truncate)'; then echo 'BLOCKED: Dangerous command detected'; exit 1; fi"
          }
        ]
      }
    ]
  }
}

フックのデバッグ方法

フックが期待通りに動作しない場合のトラブルシューティング。

1. フックの実行を確認する

フックが実行されているか確認するには、コマンドの先頭に echo を追加してログを出力する。

{
  "command": "echo \"[$(date)] Hook executed for $CLAUDE_TOOL_NAME on $CLAUDE_FILE_PATH\" >> /tmp/claude-hooks.log && npx prettier --write \"$CLAUDE_FILE_PATH\""
}

/tmp/claude-hooks.log を確認することで、フックの実行履歴が分かる。

2. よくある問題と対処

問題	原因	対処
フックが実行されない	matcherの正規表現が間違っている	ツール名と正確に一致するか確認
コマンドがエラーで止まる	コマンドの終了コードが0以外	`\|\| true` を追加
ファイルパスが空白で切れる	パスにスペースが含まれる	`\"$CLAUDE_FILE_PATH\"` でクォート
フックが遅い	コマンドの実行に時間がかかる	`head` で出力を制限

3. フックの無効化

一時的にフックを無効化したい場合は、環境変数を使う。

{
  "command": "if [ -z \"$SKIP_HOOKS\" ]; then npx prettier --write \"$CLAUDE_FILE_PATH\"; fi"
}

# フックをスキップしてセッション開始
SKIP_HOOKS=1 claude

まとめ

Hooks を活用すると、Claude Code の作業フローに「自動品質保証」のレイヤーを追加できる。手動で行っていたフォーマット、型チェック、セキュリティ確認を自動化することで、ミスを防ぎつつ作業効率も向上する。

フック自動化の詳細については、フック自動化で詳しく解説しています。キーバインド設定については、キーバインドによる効率的な入力で詳しく解説しています。

次に読むべきガイド: MCP サーバーで機能を拡張するでは、外部ツール連携によるさらなる自動化を学べる。

リファレンス

CLAUDE.md 完全ガイド - プロジェクト文脈の設定方法
中級者向け学習パス - 全体的なスキルアップ

すぐ試したい方へ

具体的な設定レシピをすぐ試したい場合は、Hook自動化Tips で実践的なテクニックを確認できます。

Hooks で作業を自動化する