scaffold-cc-hooks

scaffold-cc-hooks

まず対象プロジェクトを監査し、その後、Bash を優先した決定論的なレイアウトで Claude Code フックを生成します。

判断フロー

ユーザーの依頼内容は何ですか？

• まだフックが設定されていないプロジェクトに Claude Code フックを新規追加する場合： ライブドキュメントを確認し、プロジェクトを監査して、フックのプランを選択してから生成します。
• 既存の .claude/settings*.json または .claude/hooks/ ファイルがある場合： 既存の内容を監査し、additive または overhaul を選択してから、管理対象のフックレイヤーのみを再生成します。
• /hooks には表示されるものの、実際には一度も実行されない既存のフックがある場合： 最初の診断では、ワークスペースの信頼状態を確認します。設定やスクリプトのロジックをデバッグする前に、プロジェクトの正確なパスが ~/.claude.json にあるかを確認し、まだ信頼が有効になっていなければ、有効化を提案します。
• 既存のフックに加えて、Claude Code の機能に変更があった可能性がある場合： ファイルを書き込む前に、公式ドキュメントで最新のフックイベント一覧を確認します。ドキュメントに変更があれば、まずスキャフォールドの入力を更新します。
• 実装ではなく説明のみを求められている場合： references/hook-events.md と references/scaffold-layout.md を読み、スキャフォールドを生成せずに回答します。

クイックリファレンス

タスク	アクション
現在の公式フックモデルを確認する	https://code.claude.com/docs/en/hooks と https://code.claude.com/docs/en/hooks-guide の公式ライブドキュメントを読み、assets/hook-events.json と比較します
対象リポジトリを監査する	scripts/audit_project.sh /path/to/project を実行します
Claude Code が対象ワークスペースを信頼しているか確認する	scripts/check_workspace_trust.sh /path/to/project --json を実行します
対象ワークスペースの信頼を有効にする	scripts/check_workspace_trust.sh /path/to/project --enable を実行します
イベントカタログを確認する	references/hook-events.md を読みます
再利用可能なリポジトリ管理のスクリプトを設計する	references/reusable-scripts.md を読みます
additive と overhaul のどちらにするか決める	references/merge-strategy.md を読みます
管理対象のフックスキャフォールドを生成または更新する	`scripts/scaffold_hooks.sh --project /path/to/project --plan /path/to/plan.json --mode additive
生成したフックを設定にマージする	scripts/scaffold_hooks.sh から scripts/merge_settings.sh を呼び出すか、マージスクリプトを直接実行します
対象プロジェクトのフック用 README を再生成する	scripts/render_hooks_readme.sh --project /path/to/project --plan /path/to/plan.json を実行します

譲れないワークフロー

1. スキャフォールドを計画する前に、最新の公式 Claude Code フックのドキュメントを確認します。
2. 最新のイベント一覧、フックタイプのサポート状況、非同期ルールを assets/hook-events.json と照合します。
3. 有効にするイベントを決める前に、対象プロジェクトを詳細に監査します。
4. マージ方法を選ぶ前に、既存の .claude/settings.json、.claude/settings.local.json、.claude/hooks/、CLAUDE.md、.claude/rules/、および関連する自動化ファイルを確認します。
5. 具体的なフック計画 JSON を作成または更新します。プロジェクト固有の判断はスキャフォールドスクリプトではなく、計画に記述して、スキャフォールドの決定性を保ちます。
6. Codex、OpenCode、Git フック、GitHub Actions、またはローカルシェルで使用する可能性がある動作には、リポジトリで管理する共有スクリプトを優先します。生成される Claude フックファイルは、それらのスクリプトを呼び出す薄いアダプターにします。
7. 現在のすべてのフックイベントについて、設定で無効のままにする場合でも、管理対象のフックルートにコメント付きの bash スタブを用意します。
8. プロジェクトが無効なスタブの実行コストを負担しないよう、選択した設定ファイルには有効なイベントだけを登録します。
9. .claude/hooks/README.md を再生成し、プロジェクトで常に読みやすいイベント一覧を参照できるようにします。
10. フックが登録済みなのに動作しないとユーザーから報告された場合、または実際のスキャフォールドを完了してセットアップを確認する必要がある場合は、フックのロジックをデバッグする前に、対象プロジェクトの正確なパスに対するワークスペースの信頼状態を確認するか、確認を明示的に提案します。
11. 信頼が無効な場合、そのプロジェクトでは hasTrustDialogAccepted が false であることを説明します。ユーザーには、Claude Code の新しいセッションでダイアログを承認する方法と、フラグを直接切り替える方法の2つの復旧手段を提案します。ユーザーから依頼された場合、または信頼が有効であることの確認を明示的に依頼された場合に限り、~/.claude.json を変更します。

まず信頼状態を確認するための目安

次のような兆候がある場合は、早い段階で信頼状態を確認します。

• ユーザーが、フックが有効にならない、動作しない、または無視されていると述べている
• /hooks に想定どおりの件数のハンドラーが登録済みと表示されるのに、何も実行されない
• フックスクリプトを手動で実行すると動作するのに、Claude Code からは呼び出されない
• フックをスキャフォールドした直後に、ユーザーが実際に動作することの確認を求めている

次の手順で進めます。

1. 最初に対象パスを正規化します。信頼状態は、プロジェクトの絶対パスと完全に一致するパスに紐付けられています。
2. scripts/check_workspace_trust.sh /path/to/project --json を実行します。
3. ステータスが untrusted の場合、フラグが false であることをユーザーに伝え、有効化するか確認します。
4. ユーザーが修正を希望する場合は、scripts/check_workspace_trust.sh /path/to/project --enable を実行します。
5. 信頼状態が確認できてから、設定のマージ、フックのマッチャー、スクリプトの権限、またはフックのロジックのデバッグに進みます。

最新のドキュメントを最初に確認する

公式 Claude Code ドキュメントを信頼できる情報源とします。

• https://code.claude.com/docs/en/hooks
• https://code.claude.com/docs/en/hooks-guide

実践的なパターンやトレードオフの説明については、reading.sh の次の2つの記事を補助資料としてのみ使用します。

• https://reading.sh/claude-code-hooks-a-bookmarkable-guide-to-git-automation-11b4516adc5d
• https://reading.sh/claude-code-async-hooks-what-they-are-and-when-to-use-them-61b21cd71aad

公式ドキュメントと補助記事の内容が異なる場合は、公式ドキュメントに従い、ローカルの参照資料を更新します。

メンテナー向けの段階的な乖離チェック

このスキル自体を更新するときは、ドキュメントの乖離確認を最初のメンテナンス手順にしてください。

1. 編集当日に Claude Code の公式ドキュメントをライブ取得し、現在のイベント一覧、ハンドラーの種類、マッチャーのルール、入出力の契約、非同期動作、信頼動作を assets/hook-events.json と比較します。
2. claude --version など、利用可能なローカルのバージョン情報を確認し、更新の根拠となるソースやドキュメントの日付を記録します。
3. 乖離がある場合は、assets/hook-events.json、references/hook-events.md、スキャフォールド生成ツール、テンプレート、計画例、バリデーター、テスト、評価、薄いラッパーを含むスキャフォールド全体をまとめて更新します。
4. 乖離がない場合も、ライブドキュメントを確認したことを明記します。記憶に頼ったり、Codex や OpenCode からの推測をそのまま流用したりして、このスキルを更新しないでください。

プロジェクト分析ルール

フック構成を選ぶ前に、次の項目を調査します。

• リポジトリのルートとワークスペースの構成
• Claude Code が信頼する対象となる正確な絶対プロジェクトパス。信頼設定は ~/.claude.json 内のパスをキーにしているためです
• 言語とパッケージマネージャー
• ビルド、テスト、リンター、フォーマッターの実行方法
• タスクランナー、パッケージスクリプト、リポジトリ内のドキュメントに記載されたフレームワークのコマンド、CI ジョブ、Make／Just／Taskfile のターゲット、ローカルスクリプトなど、既存のリポジトリ管理下のコマンド実行方法
• <project>/scripts/agent-session-context.sh、<project>/scripts/agent-stop-checks.sh、アダプタースクリプト、Husky フック、GitHub Actions ジョブなど、ロジックを共有すべき再利用可能なエージェントまたは自動化スクリプト
• Turborepo、Nx、pnpm ワークスペース、Bun ワークスペース、カスタムタスクランナーなどのモノレポツール
• 既存の Claude Code 設定、ルール、フック、プラグイン、スキル
• 既存の Git フック、Husky、Lefthook、CI ゲート
• .env、シークレット、マイグレーション、ロックファイル、生成コード、インフラディレクトリなどの機密性の高いパス
• direnv、.envrc、ディレクトリごとのツール設定など、環境の再読み込み要件

まず scripts/audit_project.sh を実行し、詳細なチェックリストが必要な場合は references/project-analysis.md を読んでください。

決定論的な作業とプロジェクト固有の作業

次の項目は決定論的に扱います。

• 管理対象フックのルートパス
• イベントのスタブファイル名
• 生成される設定フラグメントの形式
• 以前に管理対象だったフックのマージ動作
• フック README の生成
• 現在の公式フックイベントすべてを網羅するイベントマニフェスト

次の項目はプロジェクト固有のままにします。

• 有効にするイベント
• イベントマッチャー
• 同期と非同期の選択
• ツールイベントの if フィルター
• タイムアウト
• カスタムフックロジックの前にイベントが実行する、設定済みのリポジトリコマンド
• カスタムフックロジックの前にイベントが処理を委譲する、再利用可能なリポジトリ管理下のスクリプト
• 有効にしたイベントスクリプト内の実際のロジック
• 更新を additive にするか overhaul にするか

再実行時のルール

このスキルを同じプロジェクトに対して再び実行する場合は、次のルールに従います。

• イベントセットに変更がないと決めつける前に、ライブドキュメントの確認を再実行します。
• 現在のフック計画が引き続き適切だと決めつける前に、プロジェクトを再監査します。
• フックが一度も実行されないとユーザーが述べた場合、またはスキャフォールドの検証が必要な場合は、生成された設定が誤っていると決めつける前に、正確なプロジェクトパスに対するワークスペースの信頼設定を再確認します。
• デフォルトでは、管理対象外のフックを保持します。
• overhaul モードでは、管理対象ルート内に以前生成されたフックを置き換え可能として扱います。
• additive モードでは、不足しているイベントがある場合や README が古い場合に更新が必要となる場合を除き、以前生成されたフックを追記専用として扱います。
• 新しい公式フックイベントがある場合は、プロジェクトで無効のままにする場合でも、新しいスタブと README の項目を追加します。

スキャフォールドのルール

• プロジェクトのフック実行環境には、Python ではなく Bash スクリプトを生成します。
• 生成する Bash のスタブには、平易な言葉でコメントを付けます。
• 生成するイベントスクリプトは main() と、編集箇所を示す単一の handle_event() で構成し、人間やエージェントが制御フローをすばやく把握できるようにします。
• フックプランでは、再利用可能なリポジトリ所有スクリプト用の言語に依存しない scripts エントリと、既存のリポジトリコマンド用の commands エントリをサポートします。生成スクリプトにパッケージマネージャー、フレームワーク、ツールチェーンの例をハードコードしないでください。
• 共有動作は、通常 scripts/ の下に置く、パスに依存しないリポジトリスクリプトにまとめます。出力プロトコルが異なる場合は、claude などのハーネス引数を渡します。生成するイベントスタブは薄いままにします。
• 生成するコマンドパスでは $CLAUDE_PROJECT_DIR を使用します。
• プロジェクトに既存のより確立された規約がない場合、管理対象のルートは .claude/hooks/generated を既定とします。
• フック設定を共有する場合は .claude/settings.json を既定とします。マシン固有の動作が必要な場合、またはプロジェクトですでにそのパターンを使用している場合に限り、.claude/settings.local.json を使用します。
• イベントマップを明確に保つため、イベントごとに管理対象スクリプトを 1 つにします。
• マージ後の設定は決定的なものにします。以前に管理対象だったハンドラーだけを削除し、無関係なカスタムフックは削除しないでください。

読み方ガイド

必要な情報	参照先
完全な監査チェックリストと最初に確認する項目	references/project-analysis.md
現在の公式イベント一覧とサポートマトリックス	references/hook-events.md
管理対象フォルダーの構成とプランファイルの形式	references/scaffold-layout.md
Claude Code、Codex、OpenCode、Git フック、CI にまたがる再利用可能なスクリプトの配置	references/reusable-scripts.md
追加と全面的な置き換えの動作	references/merge-strategy.md
Async、if、シェル、設定に関する落とし穴	references/gotchas.md

運用スクリプト

• scripts/audit_project.sh は、実際のリポジトリの情報からプロジェクトプロファイルを作成します。
• scripts/check_workspace_trust.sh は、正確なプロジェクトパスについて Claude Code のワークスペース信頼を確認または有効化します。
• scripts/scaffold_hooks.sh は、管理対象のフックツリー、マニフェスト、README、設定フラグメントを生成します。
• scripts/merge_settings.sh は、管理対象外のフックを保持しながら、以前に管理対象だったハンドラーを置き換えます。
• scripts/render_hooks_readme.sh は、マニフェストと現在のプランから .claude/hooks/README.md を再生成します。

注意点

1. async が適用されるのはコマンドフックのみです。また、トリガーとなったアクションの完了後は、非同期フックで Claude を停止したり、動作を誘導したりできません。
2. if フィールドはツールイベントでのみ機能し、Claude Code v2.1.85 以降が必要です。
3. stop_hook_active を考慮しないと、Stop フックが無限ループすることがあります。
4. フックのシェルは非対話型です。シェルプロファイルからの余計な出力によって、JSON 出力が壊れることがあります。
5. 非対話型の -p モードでは PermissionRequest は発火しません。
6. 信頼されていないワークスペースではフックは発火しません。Claude Code は ~/.claude.json の .projects["/absolute/path/to/project"] にある hasTrustDialogAccepted に基づいて実行を制御します。フックがインストール済みに見えるのに実行されない場合や、実際にスキャフォールドを作成した後は、フック設定を疑う前に scripts/check_workspace_trust.sh で信頼状態を確認してください。具体的な復旧手順については、references/gotchas.md の注意点 9 を参照してください。
7. 再利用可能な検証ロジックやコンテキストロジックを、生成される .claude/hooks/generated/events/*.sh ファイルに埋め込まないでください。リポジトリ所有のスクリプトに配置し、Claude フックからアダプターとして呼び出してください。