Hook でツール実行を自動化する

症状・対象

編集後の formatter や型チェックを忘れ、完了直前に大量のエラーが見つかる人が対象です。まず TypeScript の編集後だけ型チェックする小さな PostToolUse Hook を追加します。

最短解決

1. 既存の .claude/settings.json を退避する。
2. PostToolUse に、TypeScript ファイルだけを対象とする条件と検証コマンドを追加する。
3. .ts ファイルを一度編集し、Hook の結果を確認する。

コピペ例

既存設定がある場合は hooks キーだけをマージしてください。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "if": "toolInput.file_path.endsWith('.ts') || toolInput.file_path.endsWith('.tsx')",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit"
          }
        ]
      }
    ]
  }
}

検証を失敗として Claude に返して操作を止めたいスクリプトでは、診断を stderr に出して終了コード 2 を返します。

#!/usr/bin/env bash
set -o pipefail
npx tsc --noEmit || {
  echo "型チェックに失敗しました。最初のエラーから修正してください。" >&2
  exit 2
}

期待結果

• .ts / .tsx の編集直後に npx tsc --noEmit が走る。
• 型エラーがなければ次の処理へ進む。
• 終了コード 2 の検証スクリプトを使った場合、失敗内容が Claude へフィードバックされる。

検証

軽微な TypeScript ファイルを編集して、Hook の出力を確認します。その後、ターミナルでも同じコマンドを実行し、結果が一致することを確認します。

npx tsc --noEmit

設定自体が読み込まれない場合は、Claude Code で /doctor を実行して Hook の構文エラーを確認します。

落とし穴

• サンプルで .claude/settings.json 全体を上書きすると、既存の権限や MCP 設定を失います。必ずキー単位でマージします。
• PostToolUse は編集のたびに実行されます。全テストのような重い処理は async: true にするか、Stop 側へ分離します。
• コマンド内でファイルパスを使う場合は必ず引用し、空白やシェルメタ文字を含むパスを壊さないようにします。
• 0 は成功、2 はブロック、その他は非ブロックエラーです。用途に合う終了コードを選びます。

次の一手

• Hooks 自動化ガイド — イベントと入出力を体系的に設計する
• パーミッションモードを使い分ける — Hook が実行できるコマンド範囲を制限する

# 毎回手動でフォーマット
$ npx prettier --write src/api/users.ts
$ npx prettier --write src/api/orders.ts
# 編集のたびに忘れがち…

# PostToolUse フックで自動実行
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }]
    }]
  }
}