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 の判断によらずブロックしている」と説明できます。これが効きます。

ハンドラの種類

実際に使うイベント

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

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

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

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

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

終了コードの意味

例: 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 に与えて大丈夫か」と問われたとき、デモで見せられる素材になります。Hook と permissions.deny ルール、Git Worktrees を組み合わせた本番リポジトリ向けの三層防御は、別記事「Claude Code セーフティガイド：Hooks・権限・Git Worktrees で誤削除を防ぐ」で詳しく扱っています。

スコープ

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

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

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

同梱されている Subagent

明示的に呼び出すには @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)" のように直接指名します。

よく効く設定項目

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 との違い

長大な参照資料や、一部のタスクでしか必要ない知識は 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

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

動的なコンテキスト注入

!`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 > 個人 > プロジェクト。プラグイン由来の 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 統合プラットフォームとは を参照してください。

まとめ

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

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