Claude Code：Hooks・Subagents・Skills — 完全ガイド

Claude Code: Hooks, Subagents, and Skills — Complete Guide

Claude Code には3つの拡張レイヤーがあります。ライフサイクルの自動化のための hooks、並列タスク委譲のための subagents、再利用可能なプロンプトテンプレートのための skills です。このガイドでは、それぞれの仕組み、どんなときにどれを適用するべきか、そしてそれらを効果的に組み合わせる方法を説明します。

What This Guide Covers

Hooks、subagents、skills は、Claude Code を会話ツールからプログラム可能なAIエンジニアリング基盤へと変えます。基本的なセットアップについては、設定ガイドとモデル選択のドキュメントを参照してください。

Hooks: Deterministic Control Over Claude Code

Hooks は、Claude Code 内で何かが起きたときに実行されるイベント駆動のスクリプトです。モデルの解釈に頼るプロンプトとは異なり、hooks は幻覚を起こせない決定論的なコードとして動作します。

Why Hooks Matter

hooks がなければ、あらゆる安全策はモデルが理解するための指示に依存します。hooks があれば、ルールをシステムレベルで強制できます。危険なコマンドは実行前にブロックします。プロジェクトの文脈を自動的に注入します。監査目的で、すべてのツール呼び出しをログに記録します。

Hook Types and What They Do

The 25 Lifecycle Events

hooks は、25個の異なるライフサイクルのポイントで発火します。ブロック可能なイベントには以下が含まれます：

• UserPromptSubmit — プロンプトを送信するときに発火します。Claude が見る前に、プロンプトをブロックしたり修正したりできます。
• PreToolUse — 任意のツールが実行される前に発火します。主要なセキュリティのチェックポイントです。
• PermissionRequest — Claude が許可を求めるときに発火します。自動的に承認または拒否できます。
• Stop / SubagentStop — Claude または subagent が完了するときに発火します。継続を強制できます。
• PreCompact — 文脈のコンパクト化の前に発火します。トランスクリプトをバックアップできます。

情報提供のみのイベントはブロックできませんが、ログ出力や通知はできます：

• SessionStart / SessionEnd — セッションのライフサイクル。開始時に文脈を読み込み、終了時に後処理します。
• PostToolUse / PostToolUseFailure — ツールの完了または失敗。結果をログに記録し、リンターを実行します。
• SubagentStart — subagent が生成されます。エージェントのオーケストレーションを追跡します。
• Notification — Claude が通知を送信します。Slack にルーティングしたり、TTS をトリガーしたりできます。

Exit Code Behavior

Example: Block Dangerous Commands with PreToolUse

.claude/hooks/block-rm.sh を作成します：

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
  exit 2
else
  exit 0
fi

.claude/settings.json で設定します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

これで、rm -rf コマンドは実行前にすべてブロックされ、拒否理由が Claude に表示されます。

Example: Auto-Inject Project Context on SessionStart

#!/bin/bash
# .claude/hooks/session-start.sh
if [ -f "$PWD/CLAUDE.md" ]; then
  echo "Loaded project context from CLAUDE.md"
fi
if [ -f "$PWD/.env.example" ]; then
  echo "Environment template available at .env.example"
fi
exit 0

これは、Claude Code がディレクトリ内で起動されるたびに実行され、関連する文脈を自動的に提示します。

Hook Scopes

プロジェクト単位のフックは、チーム共有のポリシーに最適です。~/.claude/ の個人用フックは、どこでも適用されます。

サブエージェント：隔離されたコンテキストを持つ並列ワーカー

サブエージェントは、独自のコンテキストウィンドウ内でタスクを処理する専門化されたAIインスタンスです。サブエージェントが実行されると、その冗長な出力（ファイル検索、ログダンプ、多段階の推論など）は隔離されたままになります。返ってくるのは、要約のみです。

内蔵サブエージェント

Claudeはタスクの種類に基づいて自動的に委任します。@agent-name または claude --agent <name> で明示的に呼び出すこともできます。

サブエージェントを使うタイミング

次の場合はサブエージェントを使ってください：

• タスクが冗長な出力を生成し、その出力をメインのコンテキストで必要としない
• ツールの制限を強制したい（例：読み取り専用のレビュー）
• 独立したトピックについて並行で調査する必要がある
• 作業が自己完結しており、要約を返せる

次の場合はメイン会話を使ってください：

• そのタスクには頻繁な往復の洗練が必要
• 複数のフェーズで重要なコンテキストを共有している
• レイテンシが重要（サブエージェントは新規で開始する）

カスタムサブエージェントの作成

サブエージェントはYAMLフロントマター付きのMarkdownファイルです。保存先は次の通りです：.claude/agents/（プロジェクト）または ~/.claude/agents/（個人）：

---
name: code-reviewer
description: 熟練したコードレビューの専門家。品質・セキュリティ・保守性の観点でコードを積極的にレビューします。コードを書いた直後や修正した直後にすぐ使ってください。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたは、コード品質とセキュリティの高い基準を担保するシニアなコードレビュアーです。

呼び出されるとき：
1. 最近の変更を見るために git diff を実行する
2. 変更されたファイルに注力する
3. すぐにレビューを開始する

レビューのチェックリスト：
- コードは明確で読みやすい
- 関数と変数の命名が適切
- 重複したコードがない
- 適切なエラー処理
- 秘密情報やAPIキーが公開されていない
- 入力バリデーションが実装されている
- 良好なテストカバレッジ
- パフォーマンスへの配慮がなされている

優先度ごとに整理されたフィードバックを提供する：
- 重大な問題（必ず修正）
- 警告（修正すべき）
- 提案（改善を検討）

問題をどのように直すかについて、具体的な例を含めてください。

次で呼び出します： Use the code-reviewer agent to review my auth changes

または、@メンションで委任を保証する： @"code-reviewer (agent)" look at the auth changes

サブエージェントの設定オプション

サブエージェントへのスキルの事前読み込み

サブエージェントは親のスキルを継承しません。明示的に事前読み込みしてください：

---
name: api-developer
description: チームの慣習に従ってAPIエンドポイントを実装する
skills:
  - api-conventions
  - error-handling-patterns
---

APIエンドポイントを実装します。事前に読み込まれたスキルから、慣習とパターンに従ってください。

スキルの完全な内容は、単に利用可能にするだけでなく、起動時に注入されます。

分岐したサブエージェント（実験的）

分岐（フォーク）は、新規で開始するのではなく、完全な会話履歴を継承します。名前付きサブエージェントに対して必要な背景コンテキストが多すぎる場合に使ってください。

有効化： CLAUDE_CODE_FORK_SUBAGENT=1

生成： /fork draft unit tests for the parser changes

フォークは、あなたが作業を続けている間にバックグラウンドで実行されます。完了すると、結果がメッセージとして届きます。

並列調査パターン

依頼：「別々のサブエージェントを使って、認証・データベース・APIモジュールを並行して調査して」

各サブエージェントは独立して探索します。Claudeが調査結果を統合します。この方法は、調査の道筋が互いに依存しないときに最も効果的です。

スキル：再利用可能なプロンプトとワークフロー

スキルは、指示を呼び出し可能なコマンドにパッケージすることで、Claudeができることを拡張します。同じ実行手順をチャットに何度も貼り付けることがある場合は、スキルを作成してください。

スキル vs. CLAUDE.md

CLAUDE.md の内容と異なり、スキルの本文は呼び出されたときだけ読み込まれるため、長い参照用資料は必要になるまでほとんどコストがかかりません。

最初のスキルを作成する

mkdir -p ~/.claude/skills/explain-code

~/.claude/skills/explain-code/SKILL.md を作成します：

---
name: explain-code
description: 視覚的な図とたとえを使ってコードを説明します。コードの仕組みを説明するとき、コードベースを教えるとき、またはユーザーが「これはどう動くの？」と聞いてきたときに使います。
---

コードを説明するときは、必ず次を含めてください：

1. **まずはたとえ話から**：コードを、日常生活の何かにたとえて比較する
2. **図を描く**：ASCIIアートで、流れ・構造・関係性を示す
3. **コードを順を追って説明する**：何が起きるのかをステップごとに解説する
4. **落とし穴を強調する**：よくあるミスや誤解は何か？

説明は会話調にしてください。複雑な概念には、複数のたとえを使います。

自動で呼び出す：How does this code work?

直接呼び出す：/explain-code src/auth/login.ts

スキルのフロントマター参照

動的コンテキスト注入

!`command` の構文は、スキルのコンテンツが Claude に送られる前にシェルコマンドを実行します：

---
name: pr-summary
description: プルリクエストの変更を要約する
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## プルリクエストのコンテキスト
- PR diff：!`gh pr diff`
- PR コメント：!`gh pr view --comments`
- 変更されたファイル：!`gh pr diff --name-only`

## あなたのタスク
このプルリクエストを要約してください... 

コマンドは即座に実行され、Claude には出力だけが渡されます。複数行のコマンドには `! の囲みブロックを使ってください。

スキルディレクトリの構造

`plaintext
my-skill/
├── SKILL.md # メインの指示（必須）
├── template.md # Claude が埋めるためのテンプレート
├── examples/
│ └── sample.md # 例の出力
└── scripts/
└── validate.sh # Claude が実行できるスクリプト
`

SKILL.md から参照をサポートするファイルを指定し、Claude がそれらの内容と読み込みタイミングを理解できるようにします。

スキルはどこに置くか

優先度の高い場所が勝ちます：エンタープライズ > パーソナル > プロジェクト。プラグインのスキルは plugin-name:skill-name の名前空間を使います。

バンドルされたスキル

Claude Code には、すべてのセッションで利用できる組み込みスキルが含まれています：

• /simplify — 複雑なコードや説明を簡潔にする
• /debug — 体系的なデバッグのワークフロー
• /batch — 複数の対象を効率よく処理する
• /loop — タスクが完了するまで繰り返す
• /claude-api — Claude API のパターンのリファレンス

これらはプロンプトベースで、ハードコードではありません。Claude に詳細な実行手順（プレイブック）を与え、作業のオーケストレーションを可能にします。

フック、サブエージェント、スキルを組み合わせる

3つの機能は組み合わせ可能です。以下は本番環境向けのセットアップ例です：

例：セキュアなコードレビューのパイプライン

スキル（~/.claude/skills/secure-review/SKILL.md）：

`markdown

name: secure-review
description: セキュリティ重視のコードレビュー。認証、認可、またはデータ取り扱いのコードをレビューするときに使います。
context: fork
agent: Explore

disable-model-invocation: true

セキュリティ重視のコードレビューを実行します：

1. ハードコードされたシークレット、API キー、または認証情報がないか確認する
2. 入力のバリデーションとサニタイズを検証する
3. 認証および認可のロジックをレビューする
4. SQL インジェクション、XSS、およびインジェクションの脆弱性を確認する
5. エラーハンドリングが機密情報を漏らさないことを確認する
6. ファイルアップロードとパス・トラバーサル対策を確認する

重大度レベルと、特定のファイル参照を付けて調査結果を報告してください。
`

フック（.claude/settings.json）：

`json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "./scripts/run-security-linter.sh"
}
]
}
]
}
}
`

サブエージェント（.claude/agents/security-reviewer.md）：

`markdown

name: security-reviewer
description: 認証およびデータ取り扱いコードのためのセキュリティレビュー専門家
tools: Read, Grep, Glob, Bash

disallowedTools: Edit, Write

あなたはセキュリティ重視のコードレビュアーです。以下に注力してください：

• 認証・認可の欠陥
• 入力バリデーションの不足
• シークレットの漏えい
返却形式: {"translated": "翻訳されたHTML"}
• 注入（Injection）脆弱性

コードを決して変更しないでください。発見事項のみを報告してください。
`

使い方：認証コードを編集した後に /secure-review を実行するか、Claudeにセキュリティレビューアエージェントがこれらの変更を確認するよう依頼してください。PostToolUseフックは、ファイル編集のたびに自動的にセキュリティリンターを実行します。

実践的なパターン

パターン 1：コンテキストの保持

大きな出力を生成する操作にはサブエージェントを使用してください：

「サブエージェントを使ってテストスイートを実行し、失敗したテストのみをエラーメッセージとともに報告してください」

完全なテスト出力はサブエージェントのコンテキスト内に保持されます。得られるのは実行可能な要約だけです。

パターン 2：ツールの制限

安全のためにサブエージェントができることを制限してください：

`markdown

name: db-reader
description: 読み取り専用データベースクエリを実行する
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command

command: "./scripts/validate-readonly-query.sh"

`

このフックは、実行前にSQLの書き込み操作をすべてブロックします。

パターン 3：モデルルーティング

コスト最適化のために、異なるタスクを異なるモデルへ振り分けます：

`markdown

name: quick-classifier
description: 要求を種類と複雑さにより分類する

model: haiku

この要求を次のいずれかとして分類します：simple（単純）、complex（複雑）、またはresearch-heavy（調査中心）。
`

Haikuは分類に高速かつ低コストです。複雑なタスクはSonnetまたはOpusへルーティングしてください。

パターン 4：永続メモリ

セッションをまたいだ学習のためにサブエージェントを有効化します：

`markdown

name: codebase-architect
description: コードベースに関するアーキテクチャ知識を維持する

memory: project

コードパス、パターン、ライブラリの場所、主要なアーキテクチャ上の意思決定を見つけるにつれて、エージェントのメモリを更新してください。
`

サブエージェントは、会話をまたいで .claude/agent-memory/codebase-architect/ に知識を蓄積します。

OfoxAI 経由で Claude Code にアクセスする

Claude Codeは、Anthropic互換のAPIエンドポイントなら何でも動作します。OfoxAIは、拡張された思考やcache_controlを含む完全なプロトコルサポートを提供します。

設定：

• リクエストURL：https://api.ofox.ai/anthropic
• APIキー：app.ofox.ai から取得したOfoxAIキー

セットアップ手順はClaude Codeの構成ガイドを参照してください。モデル比較はClaude Opus 4.7のAPIレビューと、2026年のエージェント向け最適なAIモデルを参照してください。

まとめ

まずはスキルから始めてください。スキルは作成が最も簡単で、すぐに価値が得られます。決定論的な強制が必要になったらフックを追加します。並列作業やコンテキストの隔離が重要な場合はサブエージェントを使いましょう。

Claude Codeから最大の恩恵を得ているチームは、これを単なるチャットインターフェースではなく、プログラム可能なプラットフォームとして扱っています。その移行を可能にするのが、フック、サブエージェント、スキルというツールです。

元記事：ofox.ai/blog。