claude-hook-writer

Claude Hook Writer

ステータス：本番環境対応 バージョン：2.0.0（段階的開示により最適化） 最終更新日：2025-12-17

---

概要

安全で信頼性が高く、パフォーマンスに優れた Claude Code フックを作成するための専門的なガイダンスです。このスキルは設計上の判断を検証し、ベストプラクティスを徹底し、よくある落とし穴を防ぎます。

---

このスキルを使用するタイミング

• 新しい Claude Code フックを設計するとき
• 既存のフックコードをレビューするとき
• フックの失敗をデバッグするとき
• 遅いフックを最適化するとき
• 機密データを扱うフックを保護するとき
• フックを PRPM パッケージとして公開するとき

---

基本原則

1. セキュリティは妥協できません

フックはユーザーの権限で自動的に実行され、ユーザーがアクセスできるあらゆるファイルの読み取り、変更、削除が可能です。

常にすべての入力を検証し、サニタイズしてください。 フックは標準入力経由で JSON を受け取ります。決して無条件に信頼しないでください。

セキュリティパターンの詳細：検証を実装するときやフックを保護するときは、references/security-requirements.md を読み込んでください。

2. 機能より信頼性を優先

99％の確率でしか動作しないフックは、壊れたフックです。エッジケース（Unicode のファイル名、パス内のスペース、ツールの不足）は必ず発生します。

デプロイする前に、エッジケースをテストしてください。

信頼性パターンの詳細：エラーやエッジケースを扱うときは、references/reliability-performance.md を読み込んでください。

3. パフォーマンスは重要です

フックは操作をブロックします。5秒かかるフックの場合、Claude は処理を続けるまで5秒待つことになります。

フックは高速に保ってください。負荷の高い処理はバックグラウンドで実行してください。

パフォーマンス最適化の詳細：フックの速度を最適化するときは、references/reliability-performance.md を読み込んでください。

4. 適切に失敗させる

依存関係の不足、不正な入力、ディスクエラーは発生します。

エラーを明示的に処理してください。失敗をログに記録してください。意味のある終了コードを返してください。

---

フック設計チェックリスト

コードを書く前に、次の質問に答えてください。

このフックはどのイベントを対象にしますか？

• PreToolUse - ツール実行前（入力の変更、検証、ブロック）
• PostToolUse - ツールの完了後（フォーマット、ログ記録、クリーンアップ）
• UserPromptSubmit - ユーザー入力の処理前（検証、拡張）
• SessionStart - Claude Code の起動時（セットアップ、環境チェック）
• SessionEnd - Claude Code の終了時（クリーンアップ、状態の保持）
• Notification - 通知中（デスクトップ通知、ログ記録）
• Stop / SubagentStop - 応答の終了時（クリーンアップ、要約）
• PreCompact - コンテキストの圧縮前（重要なコンテキストの保存）

よくある間違い： 検証に PostToolUse を使うことです（手遅れです。ツールはすでに実行されています）。操作をブロックするには PreToolUse を使ってください。

このフックを実行するツールはどれですか？

具体的に指定してください。matcher: "*" はすべてのツール呼び出しで実行されます。

適切なマッチャー：

• "Write" - ファイルへの書き込みのみ
• "Edit|Write" - ファイルの変更
• "Bash" - シェルコマンド
• "mcp__github__*" - すべての GitHub MCP ツール

不適切なマッチャー：

• "*" - すべて（ログ記録やメトリクスの場合にのみ使用）

このフックにはどのような入力が必要ですか？

ツールによって提供される入力は異なります。利用可能な入力を確認してください。

# PreToolUse / PostToolUse
{
  "input": {
    "file_path": "/path/to/file.ts",     // Read, Write, Edit
    "command": "npm test",                // Bash
    "old_string": "...",                  // Edit
    "new_string": "..."                   // Edit
  }
}

使用する前に、フィールドが存在することを検証してください。

FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
if [[ -z "$FILE" ]]; then
  echo "No file path provided" >&2
  exit 1
fi

これはコマンドフックとプロンプトフックのどちらにすべきですか？

コマンドフック（type: "command"）：

• 高速（ミリ秒単位）
• 決定論的
• 適した用途：フォーマット、ログ記録、ファイルチェック

プロンプトフック（type: "prompt"）：

• 低速（2～10秒）
• コンテキストを認識（LLM を使用）
• 適した用途：複雑な検証、セキュリティ分析、意図の検出

経験則： LLM による推論が必要な場合を除き、コマンドフックを使用してください。

成功または失敗を伝える終了コードはどれですか？

• exit 0 - 成功（操作を続行）
• exit 2 - 操作をブロック（エラーを Claude に表示）
• exit 1 など - ブロックしないエラー（ログに記録して続行）

PreToolUse フックの場合：

• exit 2 はツールの実行をブロックします
• exit 0 は実行を許可します（必要に応じて変更した入力を渡します）

PostToolUse フックの場合：

• 終了コードでは操作をブロックできません（ツールはすでに実行済みです）
• 成功時は exit 0 を、エラーのログ記録には exit 1 を使用してください

---

よくある落とし穴トップ5（必ず把握）

落とし穴 #1：変数を引用符で囲まない

エラー：スペースや特殊文字を含むファイル名でフックが壊れます

理由：引用符で囲まれていない変数は、空白で分割されます

例：

# ❌ WRONG - breaks on "my file.txt"
cat $FILE
prettier --write $FILE
rm $FILE

# ✅ RIGHT - handles spaces and special chars
cat "$FILE"
prettier --write "$FILE"
rm "$FILE"

重要な理由：スペース（"my file.txt"）、Unicode（"文件.txt"）、特殊文字（"file (1).txt"）を含むファイルはよくあります。

引用符のベストプラクティスについて：包括的な入力処理のパターンについては、references/security-requirements.md を読み込んでください。

---

落とし穴 #2：入力を検証せずに信頼する

エラー：フックが悪意のある入力や不正な入力に対して実行されます

理由：使用前に JSON フィールドを検証していません

例：

# ❌ DANGEROUS - no validation
FILE=$(jq -r '.input.file_path')
rm "$FILE"  # Could delete ../../../etc/passwd

# ✅ SAFE - validate first
FILE=$(jq -r '.input.file_path // empty')
[[ -n "$FILE" ]] || exit 1
[[ "$FILE" == "$CLAUDE_PROJECT_DIR"* ]] || exit 2
[[ "$FILE" != *".."* ]] || exit 2
rm "$FILE"

重要な理由：パストラバーサル攻撃を防ぎ、プロジェクト外のファイルを保護し、不正な入力によるクラッシュを防ぎます。

包括的なセキュリティパターンについて：references/security-requirements.md を読み込んでください。

---

落とし穴 #3：処理を長時間ブロックする

エラー：フックに 30 秒以上かかり、Claude をブロックします

理由：コストの高い処理（テスト、ビルド）をフック内で同期的に実行しています

例：

# ❌ BLOCKS Claude for 30 seconds
npm test
npm run build

# ✅ RUN IN BACKGROUND - returns immediately
(npm test > /tmp/test-results.log 2>&1 &)
(npm run build > /tmp/build.log 2>&1 &)
exit 0

重要な理由：遅いフックはユーザー体験を損ないます。PreToolUse は 100ms 未満、PostToolUse は 500ms 未満を目標にしてください。

パフォーマンスの最適化について：references/reliability-performance.md を読み込んでください。

---

落とし穴 #4：ブロックに誤った終了コードを使う

エラー：PreToolUse フックが実際には処理をブロックしません

理由：exit 2 ではなく exit 1 を使用しています

例：

# ❌ WRONG - logs error but doesn't block
if [[ $FILE == ".env" ]]; then
  echo "Don't edit .env" >&2
  exit 1  # Tool still runs!
fi

# ✅ RIGHT - actually blocks
if [[ $FILE == ".env" ]]; then
  echo "Blocked: .env is protected" >&2
  exit 2  # Tool is blocked
fi

重要な理由：exit 1 はエラーを記録するだけです。PreToolUse フックでブロックするには exit 2 が必要です。

終了コードのパターンについて：完全なフック応答パターンについては、references/hook-templates.md を読み込んでください。

---

落とし穴 #5：ツールが存在すると決めつける

エラー：依存関係が見つからないとフックがクラッシュします

理由：ツールを使う前にインストールされているか確認していません

例：

# ❌ BREAKS if prettier not installed
prettier --write "$FILE"

# ✅ SAFE - check first
if command -v prettier &>/dev/null; then
  prettier --write "$FILE"
else
  echo "prettier not installed, skipping" >&2
  exit 0  # Success exit, just skip
fi

重要な理由：すべてのツールをインストールしているとは限りません。フックは、依存関係がなくても適切に動作を縮退させる必要があります。

信頼性のパターンについて：references/reliability-performance.md を読み込んでください。

---

重要なルール

必ず行うこと

✅ 使用前にすべての JSON 入力を検証する（jq -r '... // empty'） ✅ パスやユーザー入力を含むすべての変数を引用符で囲む ✅ スクリプトには絶対パスを使用する（${CLAUDE_PLUGIN_ROOT}/...） ✅ 機密ファイル（.env、*.key、認証情報）をブロックする ✅ 必要なツールが存在するか確認する（command -v toolname） ✅ 妥当なタイムアウトを設定する（PreToolUse では 5 秒未満） ✅ 重い処理はバックグラウンドで実行する ✅ エッジケース（スペース、Unicode、特殊文字）でテストする ✅ PreToolUse フックでブロックするには exit 2 を使用する ✅ エラーは stdout ではなく stderr またはファイルに記録する

絶対に行わないこと

❌ JSON 入力を検証せずに信頼する ❌ 変数を引用符で囲まずに使用する（"$FILE" ではなく $FILE） ❌ スクリプトに相対パスを使用する ❌ パスのサニタイズを省略する（.. を確認し、プロジェクト内であることを検証する） ❌ ツールがインストールされていると決めつける ❌ PreToolUse フックで 1 秒を超えてブロックする ❌ ブロックしたいときに exit 1 を使用する（exit 2 を使用する） ❌ 機密データを stdout やファイルに記録する ❌ 本当に必要な場合を除き、matcher: "*" を使用する

---

リファレンスを読み込むタイミング

特定のフックの側面に取り組む際は、リファレンスファイルを読み込んでください。

セキュリティ要件（references/security-requirements.md）

次の場合に読み込みます：

• 入力の検証とサニタイズを実装する
• 機密データを扱うフックを保護する
• 機密ファイル（.env、キー、認証情報）をブロックする
• パストラバーサル攻撃を防ぐ
• セキュリティの脆弱性とベストプラクティスを理解する
• 悪意のある入力でセキュリティをテストする

信頼性とパフォーマンス（references/reliability-performance.md）

次の場合に読み込みます：

• 依存関係やツールが見つからない場合に対処する
• タイムアウトを設定し、遅い処理に対処する
• フックのパフォーマンスを最適化する（目標は 100ms 未満）
• 重い処理をバックグラウンドで実行する
• コストの高い結果をキャッシュする
• エッジケース（Unicode、スペース、深い階層のパス）でテストする
• コストの高い処理の重複を排除する

コードテンプレート（references/code-templates.md）

次の場合に読み込みます：

• 新しいフックを開始し、動作するサンプルが必要な場合
• 保存時のフォーマット機能を実装する場合
• 機密ファイルの変更をブロックする場合
• コマンドや操作をログに記録する場合
• プロンプトベースのセキュリティ分析を使用する場合
• 特定のユースケースに合わせてテンプレートをカスタマイズする場合

テストとデバッグ（references/testing-debugging.md）

次の場合に読み込みます：

• フックのテストケースを作成する場合
• フックの失敗や予期しない動作をデバッグする場合
• エッジケース（不正なJSON、フィールドの欠落）を使ってテストする場合
• トランスクリプトでフックの実行を確認する場合（Ctrl-R）
• フックのパフォーマンスをプロファイリングする場合
• 自動テストスイートを作成する場合

公開ガイド（references/publishing-guide.md）

次の場合に読み込みます：

• PRPM レジストリにフックを公開する場合
• パッケージマニフェスト（prpm.json）を作成する場合
• 高度なオプションを使って hook.json を設定する場合
• continue、stopReason、suppressOutput、systemMessage を使用する場合
• ユーザー向けの README.md を作成する場合
• バージョン管理と公開コマンドを理解する場合

クイックリファレンス（references/quick-reference.md）

次の場合に読み込みます：

• 構文をすばやく確認する必要がある場合（終了コード、jq パターン）
• 環境変数を確認する場合
• よく使う bash パターン（ファイル検証、バックグラウンド実行）を探す場合
• フックイベントとマッチャーを確認する場合
• パフォーマンスのヒントをまとめて確認する場合
• JSON 入力の構造を確認する場合

---

最終チェックリスト

フックを公開する前に：

• jq ですべての stdin 入力を検証している
• すべての変数を引用符で囲んでいる
• スクリプトに絶対パスを使用している
• 機密ファイル（.env、*.key など）をブロックしている
• ツールが見つからない場合も適切に処理している
• 妥当なタイムアウトを設定している（PreToolUse では 5 秒未満）
• エラーを stdout ではなく stderr またはファイルに記録している
• エッジケース（空白、Unicode、不正な JSON）を使ってテストしている
• 実際の Claude Code セッションでテストしている
• README に依存関係を記載している
• セマンティックバージョニングを使用している
• 説明とタグが明確である

---

同梱リソースの使用

このスキルには、必要に応じて読み込める 6 つのリファレンスファイルが含まれています：

セキュリティと信頼性（2 ファイル）：

• security-requirements.md - 入力検証、パスのサニタイズ、機密ファイルのブロック
• reliability-performance.md - エラー処理、タイムアウト、パフォーマンスの最適化

実装（2 ファイル）：

• code-templates.md - 動作するフックのサンプル（保存時のフォーマット、機密ファイルのブロック、ロガーなど）
• quick-reference.md - 構文のすばやい確認（終了コード、jq パターン、環境変数）

特定の知識が必要になったときに、リファレンスを必要に応じて読み込んでください。読み込むタイミングについては「リファレンスを読み込むタイミング」のセクションを参照してください。

---

リソース

• Claude Code フックのドキュメント
• PRPM フックパッケージ

---

最終確認日：2025-12-17 | バージョン：2.0.0