注目 Hooks Automation Tutorial

Claude Code Hooks 入門チュートリアル：自動化開発ワークフローを構築

Claude Code Hooks の日本語入門チュートリアル。ゼロから Hooks を学び、10+ の実践例、よくあるエラーのトラブルシューティング、ベストプラクティスガイドを含みます。

2026年1月19日 • 12 min read • 著者：Claude World

Claude Code に自動で lint、テスト、セキュリティチェックを実行させたいですか？Hooks がその機能です。このチュートリアルでは、Hooks のコア概念と実践的な応用をゼロから習得します。

Hooks とは？

簡単に言えば、Hooks は Claude のアクションのインターセプターです：

コマンドを入力 → [Hook がインターセプト] → Claude が実行 → [Hook がチェック] → 完了

以下のタイミングで独自のロジックを挿入できます：

タイミングHook 名用途
ツール実行前PreToolUse危険な操作をブロック、リマインダーを追加
ツール実行後PostToolUse自動 lint、テスト実行
タスク完了時Stopテストが通るまで終了しない
セッション開始時SessionStart環境をロード、情報を表示

5分クイックスタート

ステップ1：設定ファイルを作成

プロジェクトディレクトリに .claude/settings.json を作成：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'ファイルが書き込まれました'",
            "onFailure": "ignore"
          }
        ]
      }
    ]
  }
}

ステップ2：Hook をテスト

Claude Code を起動：

claude

Claude にファイルを作成させます：

あなた：hello.txt ファイルを作成して、内容は "Hello World"

Claude がファイルを作成した後、ファイルが書き込まれました と出力されます。

おめでとうございます！最初の Hook が動作しています。

コアコンセプト

Hook の構造

各 Hook 設定には3つの部分があります：

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "インターセプトするツール",
        "hooks": [
          {
            "type": "command または prompt",
            "command": "実行するコマンド",
            "onFailure": "失敗時の処理"
          }
        ]
      }
    ]
  }
}

Matcher（マッチャー）

Matcher説明
"Write"Write ツールのみインターセプト
"Edit"Edit ツールのみインターセプト
"Bash"Bash ツールのみインターセプト
"Read"Read ツールのみインターセプト
"*"すべてのツールをインターセプト
"Write|Edit"Write または Edit をインターセプト

Hook タイプ

1. Command Hook（コマンド実行）

{
  "type": "command",
  "command": "npm run lint",
  "onFailure": "warn"
}

2. Prompt Hook（AI で判断）

{
  "type": "prompt",
  "prompt": "このコマンドが安全かチェックしてください。rm -rf が含まれていたら 'block' を返してください。そうでなければ 'approve' を返してください。"
}

onFailure オプション

オプション動作
"block"コマンド失敗時に操作をブロック
"warn"警告を表示して続行
"ignore"失敗を無視

10の実践例

1. 自動フォーマット（書き込み後に lint）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\"",
            "onFailure": "warn"
          }
        ]
      }
    ]
  }
}

2. 自動テスト実行

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --passWithNoTests",
            "onFailure": "warn"
          }
        ]
      }
    ]
  }
}

3. 危険なコマンドをブロック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "コマンドに危険な操作（rm -rf、DROP TABLE、git push --force）が含まれているかチェックしてください。含まれていたら 'block' を返してください。そうでなければ 'approve' を返してください。"
          }
        ]
      }
    ]
  }
}

4. 機密ファイルの読み取りを禁止

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "ファイルパスに .env、secret、credential、password が含まれていたら 'block' を返してください。そうでなければ 'approve' を返してください。"
          }
        ]
      }
    ]
  }
}

5. API Key 漏洩チェック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "コンテンツに API key（sk_、api_key、token）がないかスキャンしてください。見つかったら 'block' を返して説明してください。そうでなければ 'approve' を返してください。"
          }
        ]
      }
    ]
  }
}

6. テストが通るまで終了を強制しない

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npm test",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

7. セッション開始メッセージを表示

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Claude Code 開始 - プロジェクト：'$(basename $(pwd))",
            "onFailure": "ignore"
          }
        ]
      }
    ]
  }
}

8. TypeScript 型チェック

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit",
            "onFailure": "warn"
          }
        ]
      }
    ]
  }
}

9. Git コミット前チェック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "コマンドが git commit または git push の場合、テストが通っていることを確認してください。不明な場合は 'ask' を返してユーザーに確認してください。そうでなければ 'approve' を返してください。"
          }
        ]
      }
    ]
  }
}

10. 機密ディレクトリの保護

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "ファイルが auth/、payment/、admin/ ディレクトリにある場合、'ask' を返して確認を求めてください。そうでなければ 'approve' を返してください。"
          }
        ]
      }
    ]
  }
}

よくあるエラーのトラブルシューティング

エラー1：Hook がトリガーされない

症状：Hook を設定したが実行されない

チェックリスト：

  1. JSON フォーマットは正しいですか？jq . .claude/settings.json で検証
  2. Matcher のスペルは正しいですか？（Write であって write ではない）
  3. ファイルの場所は正しいですか？（.claude/settings.json）
  4. Claude を再起動しましたか？

解決方法：

# JSON フォーマットを検証
cat .claude/settings.json | jq .

# Claude を再起動
claude

エラー2：Command Hook が失敗

症状：Hook command failed with exit code X

一般的な原因：

  • コマンドパスが見つからない
  • 権限不足
  • コマンド自体にエラーがある

解決方法：

# まずコマンドを手動でテスト
npm test

# コマンドが PATH にあるか確認
which npm

エラー3：Prompt Hook が期待通りに動作しない

症状：Hook が誤った判断をするか、応答しない

改善方法：

悪い prompt：

{
  "prompt": "これが安全かチェックして"
}

良い prompt：

{
  "prompt": "コマンドに 'rm -rf' が含まれているかチェックしてください。含まれていたら 'block' を返してください。そうでなければ 'approve' を返してください。この2つの値のいずれかのみを返してください。"
}

エラー4：環境変数の問題

症状：$CLAUDE_FILE_PATHS が空

解決方法：特定の Hook イベントのみが特定の変数を持ちます

変数利用可能な Hook
$CLAUDE_FILE_PATHSPostToolUse（Write/Edit 後）
$CLAUDE_PROJECT_DIRすべての Hook

エラー5：無限ループ

症状：Hook が Hook をトリガーし、スタック

原因：Hook が実行するコマンドが別の Hook をトリガー

解決方法：より正確な matcher を使用するか、コマンドで他のツールをトリガーしないようにする

ベストプラクティス

1. シンプルに始める

一度に多くの Hook を設定しないでください。1つから始めます：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'ファイルが書き込まれました！'",
            "onFailure": "ignore"
          }
        ]
      }
    ]
  }
}

2. onFailure を適切に使用

シナリオ推奨設定
テストは必ず通る必要がある"onFailure": "block"
Lint は警告があってもOK"onFailure": "warn"
重要でないチェック"onFailure": "ignore"

3. レイヤー構成

PreToolUse → 危険な操作を防ぐ（セキュリティ）
PostToolUse → 自動化チェック（品質）
Stop → 完了基準を確認（デリバリー）

4. チーム共有

.claude/settings.json を Git に追加して、チームで同じ Hook を共有：

git add .claude/settings.json
git commit -m "Add Claude Code hooks for team standards"

完全な設定例

ほとんどのプロジェクトに適した開始設定：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "コマンドに危険な操作（rm -rf、DROP、--force）が含まれているかチェックしてください。含まれていたら 'block' を返してください。そうでなければ 'approve' を返してください。"
          }
        ]
      },
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "パスに .env または secret が含まれていたら 'block' を返してください。そうでなければ 'approve' を返してください。"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet 2>/dev/null || true",
            "onFailure": "ignore"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --passWithNoTests 2>/dev/null",
            "onFailure": "warn"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'プロジェクト：'$(basename $(pwd))",
            "onFailure": "ignore"
          }
        ]
      }
    ]
  }
}

次のステップ

Hooks の基礎を学んだら、推奨される次の読み物：

  1. Hooks 完全ガイド - 高度な設定とより多くの例
  2. Hooks 開発マニュアル - スクリプト開発の詳細
  3. TDD ワークフロー - Hooks で TDD を実装
  4. セキュリティベストプラクティス - セキュリティ関連の Hook 設定

まとめ

やりたいこと…この Hook を使う
危険な操作をブロックPreToolUse + prompt
自動 lint/テストPostToolUse + command
テストが通るまで終了しないStop + command
セッション開始時に実行SessionStart + command

覚えておいてください：Hooks は「提案」を「強制」に変えます。一度設定すれば、永遠に有効です。

最終更新：2026-01-19