Claude CodeのHooksの使い方｜編集後のチェックを自動化する

Claude CodeのHooksは、編集などの決まった出来事をきっかけに、あらかじめ指定した処理を動かす機能です。 記事ファイルを編集するたびに見出しや画像の説明を調べれば、確認を頼み忘れたまま作業を終える場面を減らせます。文章の事実確認と公開の判断は、人が行う工程として残します。

たとえば、記事の文章を直した後で、見出しが消えていたり画像の説明が空になっていたりすることがあります。毎回チャットで同じ確認を頼む代わりに、編集直後の検査を設定しておくと、不足した箇所をその場で見直せます。

以下は、Markdownの記事を扱う担当者向けの設定例です。Markdownは、##で見出し、[名前](URL)でリンクを表す文章の書き方です。macOS・Linux・WindowsのWSL上で、Pythonによる小さな検査を一つ動かすところから進めます。

仕様の確認日は2026年11月5日です。設定例はClaude Codeの公式資料に基づきますが、Claude Codeからの発火やOSの通知画面は実機確認していません。練習用フォルダで確かめてから、普段の記事制作へ移してください。

Claude Code Hooksで、どの確認作業を自動化するか

最初のHooksには、編集した一つのファイルを読み、決めた項目の不足を知らせる処理が向いています。 検査対象と合格条件を小さく決めると、動かなかったときも、設定と検査内容のどちらを直すか判断しやすくなります。

Hooksとスキル・CLAUDE.mdの役割を比べる

Hooksは処理を動かすタイミング、スキルは繰り返す作業の手順、CLAUDE.mdはプロジェクト共通の前提を担当します。「記事を直したら確認する」という仕事も、何を保存したいかによって置き場所が変わります。[1][6][7]

保存したいもの	使う機能	記事制作での例
毎回守る前提	CLAUDE.md	です・ます調、出典を残す
必要なときに使う手順	スキル	原稿と根拠資料を読み比べる
決まった出来事の後の処理	Hooks	編集した記事の形式を検査する

たとえば「事実を確認する」という指示をCLAUDE.mdへ書いても、それだけで検査用のプログラムが編集ごとに実行されるわけではありません。Hooksでは、編集を検知する条件と、動かすコマンドを設定ファイルに明記します。

一方、リンク先が主張を支えているか、比較の条件がそろっているかという判断は、単純な文字の検査だけでは終わりません。人やスキルによる読み直しと、Hooksによる形式確認を組み合わせると、それぞれの仕事が明確になります。

まず作業手順自体を残したい場合は、主軸記事のClaude Codeのスキルの作り方と呼び出し方を参照できます。文章で残す手順と、自動実行する処理を混ぜずに用意します。

編集後チェックと作業完了通知を選ぶ

編集後チェックは原稿の不足を見つけるため、通知は担当者が作業へ戻るために使います。両方を一度に設定するより、困っている場面に近い方を先に選ぶと、導入の成否を確かめやすくなります。

編集後チェックの例なら、画像の説明が空の原稿を用意し、編集後にその不足が報告されることを成功条件にします。通知なら、Claude Codeが入力を待っているときに、デスクトップへ知らせが届くことを確認します。

通知が届いたことは、記事の検査に合格した証拠にはなりません。反対に、検査が成功しても、担当者へ通知する処理を加えていなければデスクトップには何も出ません。何が起きたら成功かを、設定する前に一文で書いておきます。

今回の検査例は、本文を読み取って結果を返すだけにします。原稿の自動修正を最初から含めると、検査の問題なのか、修正処理の問題なのかが分かりにくいためです。まずは「不足を知らせる」ところまでを確認します。

外部の通知サービスへ送る場合は、送信先と送る内容も決める必要があります。原稿全文や会話履歴を送らずに済むなら、ファイル名と結果だけに絞れます。最初の練習では、外部サービスに接続しないローカルの検査を選びます。

PostToolUse・Notification・Stopの違い

記事ファイルの編集後に検査するなら、ツールの処理成功後に起きるPostToolUseを使います。イベントとは、Hooksを動かすきっかけになる出来事の名前です。同じ「作業の後」でも、三つのイベントは起きる場面が異なります。[1][2]

目的	イベント	何をきっかけにするか
編集したファイルを調べる	PostToolUse	指定したツールの処理が成功した後
入力待ちなどに気付く	Notification	指定した種類の通知が発生したとき
応答終了時に追加確認する	Stop	Claudeが応答を終えるとき

記事を一部直した後も、Claudeが別のファイルを読んだり説明を書いたりすることがあります。その途中の編集を確認したいならPostToolUse、返答の区切りで確認したいならStop、というようにタイミングから選びます。

Stopは仕事全体の完了証明ではありません。ユーザーの中断では発火せず、APIエラー時には別のStopFailureが使われます。作業完了を知らせたい場合も、何の終了を知らせるのかを通知文へ書くと誤解を防げます。

PostToolUseで問題を見つけても、編集はすでに済んでいます。実行前に操作を止めるPreToolUseとは役割が違うため、「不合格なら編集されない」という前提で組まないことが大切です。Hooksの公式仕様で、イベントごとの動作を確認できます。

最初に自動化しない処理を決める

練習用のHooksには、記事の公開、外部への送信、購入、ファイルの削除を含めません。検査を試すために必要な権限と、業務上の判断が必要な権限を分けると、結果を落ち着いて確かめられます。

たとえば画像の説明が空なら、「説明を追加してください」と返すところで止めます。画像生成を始める、外部の保存先へ送る、記事を公開する、といった続きの操作は、今回の検査器には持たせません。どの処理が走るかをコードから読み取れる範囲にします。

Hooksはローカルでコマンドを実行する仕組みなので、設定したプログラムの内容を確認する必要があります。配布された例を使う場合も、外部通信、追加ソフトの取得、ファイルの書き換えが含まれるかを先に読みます。名前が「チェック」でも、中身が読み取りだけとは限りません。

今回のPython例は標準ライブラリだけを使い、ネットワーク通信やモデル呼び出しを行いません。ただし、Claude Codeで文章を編集する利用自体は、ログイン先の契約や利用枠に従います。ローカルの検査と、AIを使う料金を同じものとして考えないようにします。[8]

prompt型やagent型のHooksはモデルを使う別の方式です。単純な形式確認で十分なら、まずcommand型を選び、判定できない内容だけを人の確認へ残すと、何を自動化したか説明しやすくなります。

Claude Code Hooksを設定する前の準備

練習用の作業フォルダ、Claude Code、Python、設定の保存先をそろえてからHooksを追加します。 普段の原稿や共有設定を直接変更せず、まず一つの記事を検査するための小さな環境を用意します。

Claude Codeの版と作業フォルダを確認する

Claude Codeの版はターミナルでclaude --versionを実行して確認します。2026年11月5日の公式リリース一覧では、Latestはv2.1.318でした。これは公式掲載版の確認であり、各パソコンにその版が入っていることを意味しません。[4][9]

未導入なら公式セットアップを開き、使うOSの方法を選びます。macOS・Linux・WSLのネイティブインストールは次のコマンドです。会社の端末では、管理者が指定した導入方法を先に確認します。

curl -fsSL https://claude.ai/install.sh | bash

導入後に新しいターミナルを開き、次を一行ずつ入力します。hooks-practiceは新しく作る練習用フォルダの名前で、すでに同名のフォルダがある場合は別名を選びます。

claude --version
python3 --version
mkdir hooks-practice
cd hooks-practice
pwd
mkdir -p .claude/hooks articles

pwdに表示された場所が、以後の操作の起点です。Pythonが見つからない場合は、Pythonの公式配布先など、利用環境で認められた方法で導入します。Windowsの以下の例はWSL内で行い、PowerShellへBash用のコマンドをそのまま貼らないでください。

個人用とプロジェクト用の設定を選ぶ

最初の練習には、そのプロジェクトで自分だけが使う.claude/settings.local.jsonを選びます。別の仕事で検査が動かないよう、適用範囲を狭くします。公式資料の保存先は次のとおりです。[3]

保存先	適用する範囲	使う場面
~/.claude/settings.json	同じ端末の自分の各プロジェクト	個人共通の設定
.claude/settings.json	そのプロジェクト	チームで共有する設定
.claude/settings.local.json	そのプロジェクトの自分	個人の試験や調整

先頭の~はホームフォルダを表します。先頭に~がない.claudeは、今回作ったhooks-practice内のフォルダです。似た名前の~/.claude.jsonはClaude Codeが管理する別のファイルなので、Hooksの貼り付け先にしません。

共有用のsettings.jsonへ書いた設定をチームで使うには、ファイルと検査スクリプトを相手にも渡す必要があります。自分の端末に保存しただけでは、ほかの人へ反映されません。確認後に共有します。

settings.local.jsonを手動で作った場合は、Gitで管理するプロジェクトなら除外設定も自分で確認します。個人用の設定が変更一覧に出ていないかを見ます。起動場所や権限の準備は、Claude Code・Codexのセキュリティ設定でも確認できます。

既存のsettings.jsonへ追記する場所

既存設定がある場合は、外側のhooksを一つにまとめ、その中へPostToolUseを追加します。JSONは設定名と値を組にして書く形式です。別の完成済みJSONをファイル末尾へそのまま連結すると、一つの設定ファイルとして読めなくなります。[2][10]

編集前に、使う設定ファイルを別名でコピーしておきます。すでにNotificationがあれば、PostToolUseを同じ階層の項目として追加します。PostToolUseもあるなら、その配列に今回の設定を足し、既存の処理を消さないようにします。

配列は角括弧[]、項目のまとまりは波括弧{}で囲みます。項目同士の間にはカンマが必要ですが、最後の項目の後へ余分なカンマは付けません。説明文やコメントをJSONの中へ貼り付けることも避けます。

保存後はターミナルで次を実行し、形式を確認できます。整形された内容が表示されれば構文は読めていますが、Hooksとして正しいイベントやパスを指定できたかは別に確認します。

python3 -m json.tool .claude/settings.local.json

同じキーを二つ書いても、構文検査だけでは発見できない場合があります。既存のhooksがどこにあるかをエディターで検索し、二重に作らないことが大切です。エラーが出たら、表示された行番号の前後で括弧とカンマを確認します。

実行するスクリプトと必要ツールを用意する

検査用プログラムは.claude/hooks/check_article.pyへ保存し、Pythonで読み取って実行します。スクリプトとは、決まった手順を記したファイルです。設定ファイルには実行方法、Pythonファイルには検査内容を置くと、後から変更する箇所を分けられます。

この例で必要なのはPython 3だけです。追加のパッケージ、検索サービス、APIキーは使いません。記事はarticlesフォルダ内のUTF-8の.mdファイルに限定し、その外のファイルを編集しても検査しない設計にします。

hooks-practice/
  .claude/
    settings.local.json
    hooks/
      check_article.py
  articles/
    sample.md

.claudeは先頭に点が付くため、ファイル管理画面で隠れる場合があります。エディターで練習用フォルダを開き、上の場所を指定して作成します。ファイル名の末尾に意図せず.txtが追加されていないかも確認します。

本文にあるコードは設定例として使い、実際に発火した証拠とは区別します。先にJSONの構文とPython単体の結果を確かめ、その後でClaude Codeの編集に結び付けます。保存しただけで完了とせず、「設定が見える」「処理が走る」「結果が期待どおり」の順に確認します。

起動するPythonの場所が環境ごとに違う場合は、python3が見つかるかを最初に確認します。普段のターミナルで使える別名だけに頼らず、Hooksから実行できるプログラムを指定します。

PostToolUseで記事ファイルのチェックを動かす

PostToolUseに編集ツールを指定し、渡されたファイル名をPythonへ受け渡します。 検査器は記事を読み、不足があれば理由を返します。以下の例では、編集済みの本文を勝手に直さず、担当者が結果を読める形にします。

対象ファイルと期待する結果を決める

練習ファイルはarticles/sample.mdにし、見出し・画像の説明・通常のリンクを検査します。画像の説明はaltと呼ばれ、画像を表示できないときや読み上げ時に内容を伝える文字です。まず正常な見本を保存して、比較の基準を作ります。

# お知らせの下書き

## 参加方法

申し込みの流れを説明します。

![申し込みから参加までの流れ](flow.webp)

[Claude Codeの公式ガイド](https://code.claude.com/docs/ja/hooks-guide)

flow.webpは記法を試すための仮の画像名です。この検査は画像本体の存在を確認しないため、画像の表示まで試す場合は、同じ場所へ実際の画像を用意します。文章内のリンクも、書式とリンク先の到達を別に考えます。

検査項目	この設定例の合格条件	残る確認
見出し	H2に当たる行が一つ以上ある	見出しの内容と本文が合うか
画像	画像記法があり、説明が空でない	画像が表示され、説明が適切か
リンク	通常のリンク記法があり、空や閉じ忘れを検出しない	参照先が存在し、根拠になるか

この基準は練習用に決めたもので、すべての記事へ画像を必須にする仕様ではありません。画像が不要な記事も扱うなら、後でその条件を変えます。最初は合格条件を固定したまま四つのケースを試し、検査器が何を見ているかを確かめます。

編集イベントと対象ツールを結び付ける

設定のmatcherには^(Edit|Write)$を指定します。matcherは、イベントのうち何を対象にするかを絞る条件です。この書き方では、名前がEditまたはWriteのツールに一致する場合だけ、内側のコマンドを実行します。[1]

新しい.claude/settings.local.jsonなら、次を保存できます。すでに設定がある場合は、前の節の方法で既存のhooksへ統合します。timeoutの10は、この例で決めた待ち時間の上限を秒で表した値です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "^(Edit|Write)$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check_article.py\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

CLAUDE_PROJECT_DIRはClaude Codeが渡すプロジェクトの場所です。パスを引用符で囲み、フォルダ名に空白が入っていても一つの引数として扱うようにします。今回のコマンドはmacOS・Linux・WSLのシェルを前提にしています。

ここで指定するのはファイル名ではなく、ツールの名前です。*.mdをmatcherへ書いても、Markdownファイルの選択にはなりません。ファイルの拡張子や保存場所は、次のPython側で絞ります。

Bashコマンドや外部エディターで同じファイルを書き換えても、このEdit・Write向け設定は発火しません。Claude Codeの編集時に使われたツール名まで確認すると、「保存したのに動かない」という症状を切り分けられます。

入力されたファイル名をチェック処理へ渡す

Claude Codeは、イベントの情報をJSONとしてスクリプトの標準入力へ渡します。標準入力は、プログラムが外からデータを受け取る入口です。PostToolUseでは、tool_input.file_pathから編集したファイルの場所を取り出せます。[1]

次を.claude/hooks/check_article.pyへ保存します。対象がarticles配下のMarkdownかを確かめてから読み、見出し・空の画像説明・簡単なリンク記法を調べる設定例です。記事本文や入力されたファイル名を、シェルのコマンドとして実行しません。

import json
import os
from pathlib import Path
import re
import sys


def main():
    event = json.load(sys.stdin)
    if event.get("tool_name") not in ("Edit", "Write"):
        return 0
    root = Path(os.environ["CLAUDE_PROJECT_DIR"]).resolve()
    raw_path = event["tool_input"]["file_path"]
    if not isinstance(raw_path, str) or not raw_path:
        raise ValueError("file_pathが空、または文字列ではありません")
    path = Path(raw_path)
    if not path.is_absolute():
        raise ValueError("file_pathは絶対パスで指定します")
    path = path.resolve()
    try:
        relative = path.relative_to(root / "articles")
    except ValueError:
        return 0
    if path.suffix.lower() != ".md":
        return 0
    text = path.read_text(encoding="utf-8")
    # 練習例はコードブロックを含まないMarkdownを対象にします。
    issues = []
    if not re.search(r"^## +\S", text, re.M):
        issues.append("H2見出しがありません")
    images = re.findall(r"!\[([^\]\n]*)\]\([^\n)]*\)", text)
    if not images:
        issues.append("画像記法がありません")
    elif any(not alt.strip() for alt in images):
        issues.append("画像の説明が空です")
    links = list(re.finditer(r"(?<!!)\[[^\]\n]+\]\(", text))
    if not links:
        issues.append("通常のリンク記法がありません")
    for link in links:
        tail, *_ = text[link.end():].split("\n", 1)
        target, closing, _ = tail.partition(")")
        if not closing or not target.strip():
            issues.append("リンク先が空、または閉じ括弧がありません")
            break
    if issues:
        print(f"article-check: NG articles/{relative}", file=sys.stderr)
        print(" / ".join(issues), file=sys.stderr)
        return 2
    message = f"article-check: OK articles/{relative}（簡易形式検査）"
    print(json.dumps({
        "systemMessage": message,
        "hookSpecificOutput": {
            "hookEventName": "PostToolUse",
            "additionalContext": message
        }
    }, ensure_ascii=False))
    return 0


try:
    sys.exit(main())
except (OSError, ValueError, KeyError, TypeError, AttributeError) as error:
    print(f"article-check: ERROR {type(error).__name__}: {error}",
          file=sys.stderr)
    sys.exit(1)

これはMarkdown全体を正確に解析する検査器ではありません。コードブロック内の記法、参照形式のリンク、複雑な括弧を含むURLなどは対象にしていません。本番の文書へ広げる前に、その書式に対応した検査器へ置き換えます。

正常時のJSONは、画面向けのsystemMessageとClaude向けのadditionalContextを返します。不足時は理由を標準エラー出力へ書き、終了コード2にします。読み込み失敗は別の1とし、記事の不足と実行失敗を見分けられるようにしています。

検査結果を読んで不足箇所を直す

検査結果は、対象ファイルと判定、理由、次の操作の順に読みます。OKは今回の簡易条件を通ったという意味です。文章の正確さや画像の表示まで確かめたという意味に広げないようにします。

設定とスクリプトを保存したら、練習用フォルダでClaude Codeを起動し、会話の入力欄へ/hooksと入力します。PostToolUseの一覧で今回のコマンドを選び、設定元のパスと実行内容が一致することを確認します。表示を閉じてから、次のように依頼できます。[2]

articles/sample.mdの本文に「参加前に案内を確認します。」を追記してください。
EditまたはWriteを使い、変更はこのファイルだけにしてください。
Hooksの結果を確認し、対象ファイル・判定・理由を報告してください。

結果	意味	次にすること
OKと対象名	簡易条件を通過	内容とプレビューを別に確認
NGと不足の理由	検査した結果、不足あり	該当箇所を直して再編集
何も表示されない	対象外、未発火などの可能性	ツール名と保存先を確認
ERRORとエラー名	検査を完了できなかった	入力、パス、Pythonを確認

画像の説明が空という結果なら、画像が伝える内容をaltへ足して再度編集します。実行失敗なら本文を直しても解決しません。まずスクリプト単体で同じ入力を試し、読み込める状態へ戻します。

Claudeから「確認しました」と返っただけでは、Hooksの実行記録の代わりにはなりません。表示された対象名と判定、実際の編集内容を照らし合わせ、該当する原稿を検査したことを確認します。

Claude Code Hooksを通知や整形へ広げる

基本の検査が動いたら、待ち時間の通知や対象を絞った整形を一つずつ追加します。 追加するたびに元の検査も試すと、設定の統合ミスや処理の増えすぎに気付きやすくなります。

入力待ちをデスクトップへ通知する

入力待ちの通知にはNotificationを使い、待っている理由をmatcherで絞ります。たとえばpermission_promptは権限確認待ち、idle_promptは応答後の入力待ちです。idle_promptは応答終了から約60秒、入力がない場合が目安です。[2]

macOSでは次の設定例を、既存hooks内へNotificationとして追加できます。画面の隅に「入力待ちです」と表示する例であり、記事が完成したとは通知しません。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"入力待ちです\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

まずターミナルで、上のcommandの中身を直接試します。出ない場合は「システム設定」→「通知」で「スクリプトエディタ」の通知許可を確認します。公式ガイドには、テスト通知を一度実行して設定一覧へ出す手順もあります。[2]

Linuxではnotify-sendを使う方法がありますが、デスクトップ通知を受け取る仕組みが必要です。SSH接続先や画面のないコンテナでは、コマンドだけ用意しても通知が見えない場合があります。通知を受け取りたい端末で確かめます。

Windows向けの公式例はPowerShellでダイアログを出す方法です。macOS用のosascriptをそのまま使わず、公式ガイドのOS別通知例を選びます。通知コマンドの成功と、イベントが条件どおり発生したことは分けて確認します。

コード整形は対象ファイルを絞る

自動整形を追加する場合は、使う整形ツールと対象ファイルを先に固定します。整形は、空白や改行などをルールに合わせて書き換える処理です。検査だけのHooksから変更を伴うHooksへ移るため、最初はコピーした一ファイルで差分を見ます。

Prettierを使うなら、--checkで書式を確認し、--writeで書き換えます。すでにプロジェクトへ導入したPrettierがある場合の手動確認は次の形です。未導入の端末での自動取得を避け、必要な導入は別の作業として行います。[11]

./node_modules/.bin/prettier --check articles/sample.md
./node_modules/.bin/prettier --write articles/sample.md

Hooksへ組み込むときは、入力されたファイル名を確認して、その一ファイルだけを渡します。フォルダ全体を示す.や広いワイルドカードで毎回書き換えると、今回触っていないファイルまで変わる可能性があります。

また、Prettierの終了コード1は未整形、2はPrettier側の問題です。Hooksでは2に別の意味があるため、整形ツールの結果をそのまま転送せず、検査不合格と実行失敗を明示して対応付けます。通知文だけでなく終了コードも設計します。

Hooks内の書き換えが、同じEdit・Writeのツール実行として再び発火するとは限りません。Claudeが追加で編集する場合や、別のファイル監視を併用する場合も含めて確認し、同じ修正が繰り返されないかを差分で見ます。

重い検査を毎回走らせない設計にする

編集直後には短い検査を置き、プロジェクト全体の検査は作業の区切りで行います。たとえば一つの画像説明を直すたびに全リンクへ通信すると、原稿の小さな修正でも待ち時間が発生します。検査の範囲を頻度に合わせて分けます。

検査の種類	配置の考え方	完了時に見るもの
一ファイルの形式確認	PostToolUseで短く実行	対象名と不足項目
多数のファイルの検査	手動や作業の区切りで実行	実施範囲と終了結果
通信を伴うリンク確認	必要な時点でまとめて実行	確認時刻と取得失敗

通常のHooksは処理が終わるまでClaudeを待たせます。今回の設定例ではtimeoutを10秒にしましたが、これは公式の既定値ではありません。実際の処理時間を見て設定し、時間切れを記事の合格として扱わないようにします。[1]

command型にはasync: trueで裏側へ回す方法もあります。ただし非同期の結果で、すでに進んだ操作を止めることはできません。公式リファレンスでは、通常のasync実行中はtimeoutを強制しない点も説明されています。

公開前の必須検査は、裏側で開始しただけでは完了になりません。結果が返ったことと、その結果がどの版の原稿に対するものかを確かめます。簡単な同期処理から始め、必要性が出てから非同期へ広げると確認項目を増やしすぎずに済みます。

外部ツールの取得とHooksの検査を分ける

外部ツールで資料を取得する仕事と、手元の記事を検査する仕事は分けて設定します。MCPは、Claude Codeなどから外部の機能や情報を使うための接続の仕組みです。接続できたことは、取得情報が正しいことや記事が完成したことを意味しません。

たとえば検索で公式ページを見つけ、その内容を原稿へ書き、編集後に形式を検査する流れを考えます。検索の失敗は接続先や検索条件、原稿の不足は本文、Hooksの実行失敗は設定やプログラムを調べます。担当範囲を分ければ、違う場所を直す手戻りを減らせます。

ローカル検索の準備を進めたい場合は、Claude CodeでRustXNGを使う準備と確認で、起動と検索結果の受け取りを確認できます。検索側の手順を済ませてから、保存した原稿に今回の検査を適用します。

MCPのツール名は、通常のEditやWriteとは別の名前になります。今回のmatcherはそれらを対象にしていないため、MCP側がファイルを書いた場合まで同じように検査されるとは考えません。必要なら実際のツール名と入力形式を確認して、別の設定として追加します。[1]

Hooksが不合格を返しても、出典ページの読み取りや公開判断を代行したことにはなりません。外部サービスの認証や送信範囲は接続側で確認し、形式チェックのプログラムへ秘密の値や不要な会話履歴を渡さない構成にします。

Claude Code Hooksが動かないときの確認順

Hooksの問題は、設定の読み込み、イベントの発生、プログラムの実行、結果の受け取りの順に調べます。 画面に何も出ないという理由だけで条件を全部広げず、どこまで成功したかを一段ずつ確認します。

/hooksに設定が見えるか確かめる

最初にClaude Codeの会話欄へ/hooksと入力し、PostToolUseの中に検査コマンドがあるかを確認します。現在の公式仕様では、/hooksは設定済みHooksを読むための画面です。設定元とコマンドの全文を見られますが、ここを設定編集画面として案内しないようにします。[1]

まだ起動していなければ、ターミナルで練習用フォルダへ移動し、claudeを入力します。初回の認証が必要な場合は公式の案内に従い、普段使う契約先でログインします。この起動手順の実機確認は未実施です。[8]

一覧にない場合は、pwdで確かめた場所と、設定を保存した場所を照合します。別のプロジェクトで起動した、settings.local.jsonを違う階層へ置いた、ファイル名に余分な拡張子が付いた、といった違いを先に見ます。

設定ファイルの直接編集は、通常はファイル監視によって反映されると公式資料にあります。保存後に/hooksを開き直し、新しいコマンドが見えるかを確認します。反映を確認できない場合は新しいセッションでも同じフォルダから確かめます。[1]

管理された端末では、個人のHooksが制限されている可能性もあります。JSONを直し続ける前に、/hooksに表示される出所と組織の設定を確認します。管理ポリシーを外すことで解決せず、必要な検査を管理者と相談します。

イベントとmatcherが作業に合っているか

設定が見えるのに動かない場合は、実際に使われたツール名を確認します。今回の条件はEditかWriteの成功後なので、読むだけのRead、Bashによる書き換え、外部エディターの保存は一致しません。[1]

matcherの大文字小文字も区別します。Editをeditに変えたり、イベント名をPostTooluseに変えたりしないでください。正式名を設定例と一文字ずつ照合すると、条件そのものの誤りを切り分けられます。

さらに、検査器の中でも対象を絞っています。Editが成功していても、articlesの外にあるファイルや、.txtなどMarkdown以外のファイルなら、通知を出さずに終了します。この動きは今回の意図した対象外処理です。

原因を調べるときは、同じarticles/sample.mdをEditかWriteで変更する条件へ戻します。そこで動けば、設定の読み込みより、普段の編集方法と対象条件の違いを調べます。いきなり全ツールを対象にすると、関係のない処理まで起動して原因が見えにくくなります。

必要ならターミナルからclaude --debugで新しいセッションを開始し、Hooksの実行記録を確認できます。記録には作業内容が含まれ得るため、共有する前に不要な情報を除きます。Claudeの説明だけで判断せず、イベント名と実行結果を根拠にします。[1][5]

パス・実行権限・終了コードを調べる

コマンドの実行に失敗した場合は、Python、スクリプト、記事の順に存在を確認します。今回のようにpython3 ファイル名で呼ぶ形式なら、Pythonファイルを直接実行するための実行権限は不要です。読み取り権限と、Pythonを起動できることは必要になります。

command -v python3
ls -l .claude/hooks/check_article.py articles/sample.md
python3 -m py_compile .claude/hooks/check_article.py

最後のコマンドはPythonの構文を確認し、__pycache__へ検査用のファイルを作ります。何も表示されず終了しても、記事を検査したことにはなりません。実際の入力は、次の節の方法で別に渡します。

今回の検査器の終了コード	結果	PostToolUseでの意味
0	正常、または対象外	返したJSONがあれば処理される
2	記事の条件が不足	理由をClaudeへ渡す。編集済みの内容は残る
1	入力や読込の失敗	今回のようにJSONを返さない場合は非ブロックのエラー

この表は今回の同期command型と、その出力方法に対する説明です。別イベントや別のJSON出力まで同じ動きになると一般化しません。特にPreToolUseで操作を止める仕組みと、PostToolUseで編集後に不足を伝える仕組みは分けます。[1]

No such file or directoryなら指定したファイル、Permission deniedなら読み取りや実行の権限を確認します。command not foundならプログラムの場所を見ます。権限を緩める前に、エラーが指す対象だけを確認します。

正常・不足・対象外・失敗の4ケースを試す

検査は合格する原稿だけでなく、不足する原稿と対象外の入力でも確かめます。正常時にOKが出ても、すべての入力をOKにしているだけでは役に立ちません。期待する結果を先に書き、同じ表へ実際の結果を記録します。

次は、Claude Codeを起動せずにPythonへ模擬入力を渡す手動確認用コマンドです。練習用フォルダで実行し、最後に表示される数値を終了コードとして読みます。CLAUDE_PROJECT_DIRは、この一回の子プロセスへ現在の場所を渡す指定です。

python3 -c 'import json,pathlib; print(json.dumps({"tool_name":"Edit","tool_input":{"file_path":str(pathlib.Path("articles/sample.md").resolve())}}))' \
  | CLAUDE_PROJECT_DIR="$PWD" python3 .claude/hooks/check_article.py
echo $?

ケース	試す入力	期待する結果
正常	掲載したsample.md	OKのJSON、終了0
不足	画像説明を![]へ変更	説明が空という理由、終了2
対象外	同じ内容をarticles/sample.txtへ保存	出力なし、終了0
実行失敗	入力のファイル名をarticles/missing.mdへ変更	読込のERROR、終了1

対象外と失敗は、コマンド内のファイル名を表のものへ変えます。missing.mdは作成しません。試験後はsample.mdの画像説明を元へ戻し、再び正常になることまで確かめます。

この単体試験が通っても、Claude Codeからの発火は別の確認です。最後に/hooksの一覧、実際のEdit・Write、返ってきた結果を順に確認します。通知のテストも行った場合は、Pythonの結果と混ぜずにOS名と表示結果を残します。

Claude Code Hooksをチームで運用する

チームへ広げるときは、設定の担当、試験用ファイル、止め方を一緒に共有します。 動く設定だけでなく、不足や実行失敗をどう扱うかまで決めておくと、利用者ごとに判断がばらつくことを防げます。

設定変更の担当と共有範囲を決める

共有するHooksは、変更する担当者と確認する担当者を決めてから配布します。設定ファイルだけを渡しても、呼び出すPythonファイルや必要なツールが相手の環境にないと動きません。関連するファイルと前提を一つの手順として渡します。

今回の例なら、確認済みの設定を.claude/settings.jsonへ移し、check_article.pyと練習ファイルを共有する形を検討できます。個人の通知設定はsettings.local.jsonに残すなど、全員に必要なものと個人差のあるものを分けます。[3]

共有記録	書く内容の例
目的と対象	articles内のMarkdownを編集後に検査
必要環境	使うOS、Pythonの起動方法
合格条件	H2、画像説明、簡単なリンク記法
確認した版	Claude Codeの版と確認日
障害時の対応	設定担当、単体試験、戻すファイル

新しい人の端末では、まず四つの試験ケースを実行し、その後で実際の編集に結び付けます。自分の端末で動いたという説明だけにせず、相手のPythonの場所と作業フォルダでも同じ結果になることを確かめます。

共有設定と個人設定のHooksは、単純に後のファイルだけへ置き換わるとは限りません。公式仕様では複数の設定元からHooksが統合されます。似た処理を二つの場所へ置いた場合は、/hooksで出所を見て、意図した構成になっているか確認します。[1]

不要なHooksを無効化して元に戻す

一つのHooksを止める場合は、その設定項目を元のファイルから取り除きます。ほかのHooksや権限設定も入っているため、settings.json全体を削除して止める方法は避けます。バックアップと見比べ、今回追加した項目だけを戻します。

一時的にまとめて止める設定は、外側の設定項目として"disableAllHooks": trueを指定する方法です。hooksの内側へ置く項目ではありません。既存設定のうち何が影響を受けるかを確認してから使います。[1]

{
  "disableAllHooks": true
}

上は追記するキーの位置を示す最小例で、既存ファイルを丸ごと置き換える指示ではありません。特定のHooksを残したまま個別に無効化する共通設定はないため、一件だけ止めるならその項目を外します。復帰時は保存しておいた設定と照合します。

管理者が配ったHooksは、利用者側のdisableAllHooksでは止められません。また設定の優先順位によって、別の場所のfalseが使われる場合もあります。停止したつもりでも動く場合は、/hooksの出所と有効な設定を確認します。[1]

止めた後は、練習用の記事を通常どおり編集できることと、不要になった検査が走らないことを確かめます。検査ファイルを先に消して設定だけ残すと、編集のたびに実行失敗が起きます。先に呼び出し設定を外す順序にします。

Claude Code更新後にサンプルを再確認する

Claude Codeを更新した後は、同じ練習用ファイルと入力で検査をやり直します。設定が読めること、正常・不足・対象外・失敗の結果が変わっていないこと、実際の編集から発火することを順に確認します。

更新前にclaude --versionの出力と設定のコピーを残し、更新後にも版を記録します。公式リリースの説明でHooksや設定に関する変更を確認すると、以前と違う結果が出た場合に調べる範囲を絞れます。掲載したv2.1.318を、将来も最新の版として扱わないでください。[9]

更新方法はインストール方法によって異なります。公式のネイティブインストールには自動更新があり、HomebrewやWinGetはそれぞれの更新方法を使います。普段の導入経路を確認せずに、別方式を重ねて入れないようにします。[4]

検査の記録には、版、OS、対象ファイル、期待する結果、実際の結果、確認日時を残せば比較できます。毎回すべての設定を作り直す必要はありません。まず同じ例で確かめ、結果が違った箇所だけを調べます。

Pythonや整形ツールの更新も、Claude Codeの更新とは分けて記録します。同時に複数を変えると、どれが結果に影響したか分かりにくくなります。共有する設定を変えた場合は、その変更後の版で再確認し、以前の成功記録をそのまま使わないようにします。

機械チェックの後に人が確認する項目

Hooksが形式を検査した後も、出典と本文の一致、説明の分かりやすさ、公開画面は人が確認します。画像の説明に文字が入っていても、その画像の内容を正しく伝えているとは限りません。リンク記法が整っていても、古い資料へ向いている場合があります。

記事の最後の確認では、まずタイトルで約束した答えが本文にあるかを読みます。続いて料金や仕様など変わり得る情報を出典と比べ、表や画像にも同じ条件が残っているかを見ます。文章を短くしたときに、対象や例外まで削っていないかも確認します。

実記事のプレビューでは、PCとスマートフォンの両方で見出し、段落、表、画像を開きます。コードが読みづらい、表の右端を確認しにくい、画像が読み込めない、といった表示の問題は、今回のPython検査では分かりません。

公開・修正・保留の判断を整理したい場合は、AgentSignalのAI記事を増やす前の公開前チェックも参照できます。自動化の結果と、内容を確認した担当者の判断を分けて残すことが、運用の基本になります。

最初の完了条件は、一つの記事で不足を検出し、修正後に合格へ変わり、対象外を無視し、実行失敗を区別できることです。そこまで確認できたら、必要な項目だけを少しずつ増やします。検査を増やすたびに、その検査で何が分かり、何が人の確認に残るかを明確にします。