この記事でわかること

  • Claude Codeのhooksが何をするものか
  • CLAUDE.mdやスキルとの違いと、使い分けの目安
  • hooksの置き場所と、設定して確かめるまでの手順
  • 使う前に確かめることと、つまずきやすいところ

CLAUDE.mdに「編集のあとは必ず整形する」と書いても、毎回そのとおりに動くとは限りません。この記事では、決まった処理をClaude Codeに毎回確実に動かしてもらうhooksの仕組みと、設定の前に見ておく点をまとめます。

もとにしたのは、公式ドキュメントの「hooks でアクションを自動化する」と「Hooks リファレンス」(どちらも日本語版)です。原文には2026年10月29日に目を通しました。待ち時間の上限などの値やイベントの細かい一覧は版によって変わることがあるため、ここでは主なものだけを書いています。この記事の設定の例は公式の資料にあるもので、動かして確かめてはいません。

結論: 毎回かならず動かしたい処理だけをhooksにする

hooksは、決まったタイミングで、設定したコマンドを必ず動かす仕組みです。 公式の資料では、モデルが実行を選ぶのに頼るのではなく、特定の動きが常に起きるものだと説明しています。

そのぶん、設定したコマンドは自分のパソコンの上で、毎回確認なしに動きます。判断が要る決まりはこれまでどおりCLAUDE.mdに書き、通知や整形のように、毎回同じでよい処理だけをhooksに移すと安全です。

hooksとは: 決まったタイミングで自動で動くコマンド

hooksは、自分で決めたシェルのコマンドです。Claude Codeが作業を進める流れの中には、セッションを始めたとき、ツールを使う前、ツールを使った後、応答を終えたときなど、いくつかの決まった時点があります。その時点ごとに、動かすコマンドを登録しておけます。

公式の資料は、hooksでできることの例として、編集したファイルの整形、実行の前にコマンドを止めること、入力を待っているときの通知、セッションを始めたときに情報を足すことを挙げています。

CLAUDE.md・スキルとの違い

CLAUDE.mdは毎回読ませる決まりの紙、スキルは呼んだときに読ませる手順書でした。どちらもClaudeが読んで判断する材料です。hooksは読ませるものではなく、Claude Codeそのものが決まった時点でコマンドを動かします。

項目 CLAUDE.md hooks
動き方 読んで判断 必ず実行
動くとき 会話の開始 決めた時点
向く内容 前提・目安 毎回の処理

CLAUDE.mdに何を書くかはCLAUDE.mdの書き方、ときどき頼む手順のまとめ方はClaude Codeのスキル(Skills)の使い方で紹介しています。

いつ動かせるか: 主なタイミング

hooksを動かすタイミングは「イベント」と呼ばれます。よく使われるのは次のものです。

  • SessionStart: セッションを始めたときや、再開したとき
  • UserPromptSubmit: 自分がプロンプトを送ったとき、Claudeが処理する前
  • PreToolUse: Claudeがツールを使う前。ここでは操作を止められます
  • PostToolUse: ツールの呼び出しがうまくいった後
  • Notification: Claude Codeが通知を出すとき
  • Stop: Claudeが応答を終えたとき

このほかにも多くのイベントがあり、版によって増えることがあります。全部の一覧は公式のリファレンスで確かめてください。

ツールの前後のイベントでは、「matcher」で対象を絞れます。たとえば matcher に Edit|Write と書くと、ファイルを編集したときだけ動き、コマンドの実行やファイルの読み取りでは動きません。matcher は大文字と小文字を区別します。

hooksの置き場所

hooksは設定ファイルの中に書きます。どのファイルに書くかで、効く範囲が変わります。

  • ~/.claude/settings.json: 自分のすべてのプロジェクトで動きます。このパソコンだけの設定です
  • .claude/settings.json: そのプロジェクトだけで動きます。リポジトリに入れて共有できます
  • .claude/settings.local.json: そのプロジェクトだけで動き、共有しない自分用の設定です

ほかに、組織の管理者が配る設定や、プラグイン・スキル・サブエージェントの中に書く方法もあります。最初は、自分用かプロジェクト用かを選べば足ります。

手順: 最初のhookを設定して確かめる

  1. 何を、どのタイミングで動かしたいかを決める(例: 入力を待っているときに通知を出す)
  2. 置き場所の設定ファイルを開き、hooks の項目にイベントとコマンドを書く
  3. Claude Codeの中で /hooks と入力し、そのイベントの下に設定が出ているかを見る
  4. 実際にそのタイミングを起こして、通知が出るなどの効果で動いたかを確かめる

/hooks で開く画面は読み取り専用の一覧で、それぞれのhooksがどの設定から来ているかも表示されます。動いた結果の詳しい内容は、Ctrl+Oで開く画面で見られます。

書き方の例: 入力を待っているときに通知を出す

公式の資料の最初の例は、Claudeが自分の入力を待っているときに、macOSのデスクトップに通知を出す設定です。設定ファイル(~/.claude/settings.json)に書き加えるもので、通知を表示するだけで、ファイルの作成や削除はしません。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

設定ファイルにすでに hooks の項目がある場合は、全体を置き換えずに、Notification をほかのイベントと並べて足します。JSONの書き方が崩れると設定が読まれないので、書き足した後に /hooks で表示を確かめます。

終了コードで伝わること

hooksのコマンドは、終わるときの終了コードでClaude Codeに結果を伝えます。

  • 0: 異議なし。ただし、PreToolUseで0を返しても操作を許可したことにはならず、ふだんの権限の確認はそのまま行われます
  • 2: 止める。エラーの出力に書いた理由が、イベントによってClaudeやユーザーに伝わります。止められないイベントもあります
  • それ以外: 多くのイベントでは、エラーとして知らせたうえで作業は続きます

止めたい操作は、実行の前に動くPreToolUseで扱います。ツールを使った後に動くPostToolUseでは、すでに実行された操作を元に戻せません。

使う前に確かめること

公式のリファレンスは、hooksのコマンドは自分のアカウントの権限をすべて使って動き、そのアカウントで触れるファイルを変更・削除できると注意しています。設定に加える前に、次の点を自分で確かめます。

  • コマンドの中身: 何をするコマンドかを説明できるか。分からないものは設定に入れない
  • 他人のリポジトリ: 自分が作っていないリポジトリの .claude/settings.json に、知らないhooksが入っていないか
  • 扱うファイル: .env や鍵のファイルなど、秘密の情報を読む処理になっていないか

公式の資料は、入力をそのまま信じない、シェルの変数を引用符で囲む、スクリプトは絶対パスで指定する、といった書き方の注意も挙げています。会社や組織の環境では、管理者が配った設定のhooksが先に決まっていることがあるので、追加する前に管理している人に相談します。

hooksにするか、今のままにするかの判断

目安は、「毎回、同じ処理を、確認なしで動かしてよいか」です。どの場面でも同じでよく、動いても困らない処理なら、hooksにすると頼み忘れがなくなります。場面によってやり方を変えたい処理や、取り消しにくい処理は、CLAUDE.mdやスキルに書いて、Claudeとやり取りしながら進める方が安全です。

テストの実行を毎回の流れに入れたい場合も、まずはテストの頼み方を決めてから考えます。頼み方はClaude Codeにテストを書かせる方法で紹介しています。本番のサーバーに関わる作業は、hooksで自動にする前に、読み取りだけの確認から始めます。進め方はサーバーの状態確認をClaude Codeに読み取り専用で任せる方法にまとめています。

つまずきやすいところ

  • hooksが動かない: /hooks で、正しいイベントの下に出ているかを見ます。matcher の名前は大文字と小文字まで一致させます
  • /hooks に表示されない: JSONの末尾に余計なカンマが無いか、コメントを書いていないかを確かめます。書き直しても出ないときは、セッションを起動し直します
  • command not found と出る: スクリプトは絶対パスで指定します。スクリプトのファイルに実行の権限が付いているかも確かめます
  • JSONの結果が効かない: シェルの起動時の設定ファイル(~/.zshrc など)が何かを表示していると、その文字がJSONの前に混ざります
  • 一時的に止めたい: 設定ファイルに "disableAllHooks": true を書くと、消さずにまとめて止められます。個別のhooksだけを残して止める方法はありません

まとめ

  • hooksは、決まったタイミングで、設定したコマンドを必ず動かす仕組みです
  • 判断が要る決まりはCLAUDE.md、ときどき頼む手順はスキル、毎回同じでよい処理だけをhooksにします
  • 置き場所は、自分用なら ~/.claude/settings.json、プロジェクト用なら .claude/settings.json です
  • 設定した後は /hooks で表示を確かめ、効果で動いたかを確かめます
  • コマンドは自分の権限で確認なしに動くので、中身を説明できるものだけを設定に入れます