Claude Code 完全ガイド — Hooks / Subagents / Skills の使いこなし
claude-codeai-codingdeveloper-toolsagent-orchestration

Claude Code 完全ガイド — Hooks / Subagents / Skills の使いこなし

TL;DR — Claude Code はチャット UI ではなくプログラマブルな AI エンジニアリング基盤として設計されています。Hooks はライフサイクルイベントを決定論的にフックする、Subagents は隔離されたコンテキストで並列にタスクを処理する、Skills は再利用可能なプロンプトを呼び出し可能なコマンドにまとめる。この三つを組み合わせると、レビュー・監査・規約の自動適用までエージェントの中で完結できるようになります。

なぜ Claude Code を「設定して使う」必要があるのか

2026 年に入ってから、X-jp 上のシニアエンジニア界隈での Claude Code の存在感は明らかに変わりました。日々のコードレビュー、PR 作成、デバッグ補助、ドキュメント更新まで、エディタの隣で常駐させているエンジニアは珍しくありません。

ただし、初期設定のまま使っているチームと、Hooks・Subagents・Skills まで踏み込んでいるチームの間には、生産性で実感できる差が出始めています。前者はチャット UI として便利な道具、後者はチームの規約を内部化した自動化基盤として運用している、というのが実態に近い表現です。

この記事は、Claude Code をすでに数週間以上触っているエンジニアが、その三つのレイヤーをチームで使えるレベルまで持ち上げるためのものです。インストールやモデル選定については Claude Code 設定ガイド と best AI model for coding 2026 を参照してください。

Hooks — 決定論的な歯止めをかける

Hooks は Claude Code のライフサイクルイベントに対して、シェルスクリプト・HTTP エンドポイント・MCP ツール・LLM・Subagent のいずれかを発火させる仕組みです。プロンプトでお願いするのと違って、フックは必ず動きます。ハルシネーションしません。

何が嬉しいのか

社内導入の稟議で繰り返し問われるのが「LLM が壊滅的なコマンドを実行する可能性をどう抑えているか」です。プロンプトに「危険なコマンドは実行しないでください」と書いてあるだけ、では情シス審査を通せません。Hooks は実行前の PreToolUse でコマンドを正規表現マッチして拒否できるので、技術的に「LLM の判断によらずブロックしている」と説明できます。これが効きます。

ハンドラの種類

種類中身向いている用途
commandstdin で JSON を受け取るシェルスクリプト危険コマンドの遮断、ローカル検証
httpHTTP POST エンドポイント集約ポリシー、リモートロギング
mcp_tool接続済み MCP サーバーのツール外部スキャナとの連携
prompt単発の LLM 評価「これは秘密情報っぽいか」のセマンティック判定
agentSubagent による検証多段の意味的チェック

実際に使うイベント

ライフサイクルイベントは 25 種類ありますが、最初に押さえるのは次のあたりで十分です。

ブロック可能（実行を止められる）系:

  • UserPromptSubmit — プロンプト送信時。送信前に書き換えやブロックができます。
  • PreToolUse — ツール実行直前。セキュリティ上の主要関門。
  • PermissionRequest — Claude が許可を求めたとき。自動承認/自動拒否を組めます。
  • Stop / SubagentStop — Claude や Subagent が終了したとき。続行を強制できます。
  • PreCompact — コンテキスト圧縮の直前。トランスクリプトのバックアップに。

情報系（止められないが、ログ・通知に使える）:

  • SessionStart / SessionEnd — セッション開始時にコンテキストを注入、終了時に後始末。
  • PostToolUse / PostToolUseFailure — ツール実行の成功/失敗時。lint や監査ログに。
  • SubagentStart — Subagent が起動したとき。エージェント編成の追跡に。
  • Notification — Claude が通知を送るとき。Slack や読み上げに転送。

終了コードの意味

コード意味
0成功。stdout を JSON として解釈し、判断に使う。
2ブロッキングエラー。stderr の内容が Claude に渡され、対象アクションが止まる。
1 その他非ブロッキング。stderr 1 行目が表示されるが、実行は続行。

例: PreToolUse で rm -rf を遮断する

.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: "破壊的コマンドのため 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"
          }
        ]
      }
    ]
  }
}

これで、Claude が何をどう考えていても、rm -rf を含むコマンドは実行前に止まります。情シスから「ファイル書き込み権限を Claude Code に与えて大丈夫か」と問われたとき、デモで見せられる素材になります。

スコープ

場所適用範囲
~/.claude/settings.jsonすべてのプロジェクト
.claude/settings.jsonプロジェクト単位（チーム共有）
.claude/settings.local.jsonプロジェクト単位（個人、git 管理外）
Skill / Subagent のフロントマターそのコンポーネントが動いている間のみ

チームで揃えたいポリシーはプロジェクトの .claude/settings.json にコミットしておきます。個人の好みは ~/.claude/ に置くと衝突しません。

Subagents — 隔離されたコンテキストで並列に動かす

Subagent は独自のコンテキストウィンドウで動く専用エージェントです。冗長な検索結果や試行錯誤の中身は Subagent の中に閉じ込めて、メインの会話には要約だけが返ってきます。

同梱されている Subagent

名前モデルツール用途
ExploreHaiku読み取り専用コードベース探索
Plan継承読み取り専用プランモードの調査
General-purpose継承全ツール多段の汎用タスク

明示的に呼び出すには @agent-name または claude --agent <name> を使います。

どう使い分けるか

Subagent が向いているのは、出力が長くてメインのコンテキストを汚したくない調査、ツール権限を絞りたいレビュー、独立した複数トピックの並列探索です。逆に、何度も対話的に詰める必要があるタスクや、文脈を引き継ぎ続ける必要がある仕事は、メイン会話に置いたままのほうが軽いです。

カスタム Subagent の書き方

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: コードレビューの専任。コードを書いたり編集したりした直後に必ず呼び出してください。
tools: Read, Grep, Glob, Bash
model: sonnet
---

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

呼び出されたとき:
1. git diff で直近の変更を確認
2. 修正されたファイルに集中
3. すぐにレビューを開始

チェック項目:
- 可読性、命名、重複
- エラーハンドリングの抜け
- シークレットや API キーの漏洩
- 入力バリデーション
- テストカバレッジ

指摘は優先度別に整理してください:
- Critical（必ず修正）
- Warning（修正推奨）
- Suggestion（検討）

呼び出し: 「コードレビュアーのエージェントに認証周りの変更を見てもらって」と言うか、@"code-reviewer (agent)" のように直接指名します。

よく効く設定項目

フィールド用途
toolsこのエージェントが使えるツールのホワイトリスト
disallowedToolsブラックリスト（読み取り専用化など）
modelsonnet / opus / haiku / inherit / 完全 ID
permissionModedefault / acceptEdits / bypassPermissions 等
skills起動時に読み込む Skills
hooksこのエージェント限定のフック
memoryuser / project / local の永続メモリ
maxTurns自走する最大ターン数

LINE Bot や Slack Bot 開発での実用例

国内向けの LINE Bot や社内 Slack Bot を作っているとき、Subagent はスケッチ用の作業空間として便利です。たとえば「LINE の Webhook ペイロードのサンプルを 5 種類想定して、それぞれに対するハンドラの分岐を試案として書いて」というタスクは、メイン会話で進めるとペイロード JSON だけで数千トークン消費します。これを general-purpose Subagent に振っておくと、メインのレビュー会話を汚さずに 5 案が並行で動き、戻ってくるのは完成したハンドラ案だけ、という運用ができます。Slack Bot で複数のスラッシュコマンドを並列に実装したいときも同じパターンが効きます。

Skill のプリロード

Subagent は親の Skill を継承しません。明示的に書きます。

---
name: api-developer
description: チーム規約に沿って API エンドポイントを実装
skills:
  - api-conventions
  - error-handling-patterns
---

起動時に Skill の本文がコンテキストに展開されるので、規約の参照漏れがなくなります。

Skills — 同じプロンプトをコピペし続けるのを止める

同じ手順書を毎回 Claude に貼っているなら、それは Skill にすべきサインです。Skill は /skill-name のスラッシュコマンドとして呼び出せ、description に書いた条件に合致したときには Claude が自動で読み込みます。

CLAUDE.md との違い

CLAUDE.mdSkills
読み込みセッション開始時に必ず呼び出されたときだけ
向いている内容常駐させたい規約・前提手順書、プレイブック、ワークフロー
コスト常時コンテキスト消費使うときだけ

長大な参照資料や、一部のタスクでしか必要ない知識は Skills に逃がすほうがコンテキスト効率が良いです。

最小構成の Skill

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

~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: コードの仕組みを図と例えで説明する。コードの動作説明、コードベースの教育、「これどう動くの？」と聞かれたときに使う。
---

コードを説明するときは必ず:

1. **例え話から始める** — 日常的なものに例える
2. **図を描く** — ASCII で構造や流れを示す
3. **段階的に説明する** — 何が起きているかを順を追って
4. **落とし穴を指摘する** — よくある誤解や勘違いに触れる

会話的なトーンで。複雑な概念は例えを複数使う。

明示呼び出し: /explain-code src/auth/login.ts

フロントマターの主要項目

フィールド用途
name表示名、/slash-command の名前
descriptionClaude が自動読み込みするときの判断材料
disable-model-invocation自動読み込み禁止（デプロイ系など）
user-invocablefalse で / メニューから隠す（背景知識のみ）
allowed-toolsSkill 有効時にノンプロンプトで使えるツール
context: fork隔離 Subagent で実行
agentfork 時に使う Subagent タイプ
model / effortモデルや推論強度の上書き
paths自動有効化する glob パターン

動的なコンテキスト注入

!`command` の記法で Skill 本文が Claude に届く前にコマンドを実行できます。

---
name: pr-summary
description: PR の変更内容をまとめる
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## PR コンテキスト
- diff: !`gh pr diff`
- コメント: !`gh pr view --comments`
- 変更ファイル: !`gh pr diff --name-only`

## あなたの仕事
この PR を要約してください...

コマンドは即時実行され、Claude には出力だけが渡ります。これは gh だけでなく git、社内 CLI、検索ツールなど、決定論的に取りたい情報すべてに使えます。

配置場所と優先度

場所パススコープ
Enterprise管理設定組織全体
個人~/.claude/skills/<name>/SKILL.md全プロジェクト
プロジェクト.claude/skills/<name>/SKILL.mdそのプロジェクト
プラグイン<plugin>/skills/<name>/SKILL.mdプラグイン有効時

優先度は Enterprise > 個人 > プロジェクト。プラグイン由来の Skill は plugin-name:skill-name の名前空間で衝突を避けます。SI 系の大企業で全社的にコーディング規約を強制したい場合、Enterprise レイヤに置けば末端のエンジニアが上書きできない、という運用設計が可能です。

三つを組み合わせる

ここまで個別に説明してきましたが、本領は組み合わせたときに出ます。

例: セキュアレビューパイプライン

Skill (~/.claude/skills/secure-review/SKILL.md):

---
name: secure-review
description: 認証・認可・データ取り扱いの変更時に呼ぶセキュリティ重点レビュー
context: fork
agent: Explore
disable-model-invocation: true
---

セキュリティ観点で以下をチェック:

1. ハードコードされたシークレット・API キー・認証情報
2. 入力バリデーションとサニタイゼーション
3. 認証/認可ロジック
4. SQL/XSS/各種インジェクション
5. エラーメッセージからの情報漏洩
6. ファイルアップロードとパストラバーサル

深刻度別に報告し、ファイル参照を必ず付ける。

Hook (.claude/settings.json):

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

Subagent (.claude/agents/security-reviewer.md):

---
name: security-reviewer
description: 認証・データ処理周りのセキュリティレビュー専任
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write
---

セキュリティ観点のレビュアー。コードは絶対に書き換えず、所見だけを報告する。

これで、認証コードを編集すると PostToolUse フックが lint を自動実行し、必要に応じて /secure-review で深いレビューを呼び出し、書き換えが許されない security-reviewer Subagent が監査担当として常駐する、という構成ができます。情シスへの説明として「LLM はレビュアーとして使い、書き込み権限は別系統で制御している」と言える形になります。

現場で効く小さなパターン

コンテキスト保護 — テストスイートの全出力をメインに残すと一瞬で context が溢れます。「Subagent でテストを走らせて、失敗したテストとそのエラーだけ要約して」と振ると、メインに戻るのは要点だけ。

ツール制限 — DB クエリを許す Subagent には Bash のみを許可し、さらに PreToolUse フックで SELECT 以外を拒否する。プロンプトで縛る代わりに、技術的に書き込み不能にできます。

モデル別ルーティング — 分類タスクは model: haiku の Subagent に任せ、複雑な実装は Sonnet/Opus に戻す。料金とレイテンシの両方が下がります。

永続メモリ — memory: project を付けた Subagent はセッションを跨いで .claude/agent-memory/ に学習を蓄積します。コードベースの構造把握を担う「アーキテクト役」を置くと、新メンバーオンボーディングのコストが目に見えて下がります。

Ofox 経由で Claude Code を使う

Claude Code は ANTHROPIC_BASE_URL を切り替えるだけで、Anthropic 互換の任意のエンドポイントに接続できます。Ofox は Anthropic ネイティブプロトコルを https://api.ofox.ai/anthropic で提供しており、Extended Thinking、cache_control、Streaming すべてが Anthropic 直契約と同じ形で動きます。社内ポリシーで海外 SaaS への直接通信が承認しづらい、JPY 建ての請求書と適格請求書（インボイス）が必要、という日本企業特有の事情がある場合は検討する価値があります。設定方法は Claude Code 設定ガイド にまとめています。Claude Opus 4.7 を Claude Code でどう使い分けるかは Claude Opus 4.7 API レビュー も参考になります。複数モデルをまとめて扱う基礎については AI API 統合プラットフォームとは を参照してください。

まとめ

機能役割使うとき
Hooks決定論的なライフサイクル制御セキュリティ、ロギング、コンテキスト注入、遮断
Subagents隔離された並列ワーカー並列タスク、冗長出力の隔離、ツール制限
Skills再利用可能なプロンプト繰り返しの手順、規約、チームの暗黙知

最初に手を入れるなら Skills です。一番作りやすく、効果も早く出ます。決定論的な歯止めが必要になったら Hooks、コンテキストや権限の隔離が欲しくなったら Subagents という順で広げていくと、無理なくチームの運用に組み込めます。

Claude Code から最大の効果を引き出しているチームは、これをチャット UI ではなくプログラマブルな基盤として扱っています。Hooks・Subagents・Skills は、その移行を可能にする三点セットです。

関連記事

Cursor / Claude Code / Cline にカスタム API を接続する完全ガイド

← 記事一覧へ戻る