Claude Codeの拡張｜CLAUDE.md・hooks・subagents・MCP

ここまでの5章で、Claude Code を入れ、指示を出し、詰まりを抜け、権限を設計してきました。この章は道具そのものを作り変える話です。拡張は名前を覚えても使えません。役に立つのは「いまの不満はどれで解けるのか」という対応表です。

使い分けの地図 ― 4つの問いで決まる

拡張は6つありますが、考えることは4つだけです。お願いで足りるか／確実に効かせたいか／別の文脈に分けたいか／外部に繋ぎたいか——この順に自問すれば、だいたい一意に決まります。

お願いで足りるか

たまに抜けても致命的でないなら言葉で足ります。→ CLAUDE.md（全体の前提）／Skills（特定作業の手順）

確実に効かせたいか

一度でも抜けたら困るなら、仕組みで止める。→ hooks。設定が有効で、対象イベントと条件に一致したときに実行されます。

別の文脈に分けたいか

大量の出力で本筋を埋めたくないなら、外でやらせて結論だけ受け取る。→ subagents

外部に繋ぎたいか

AIが知りようのない情報（DBの現在値、課題管理の中身）が要るなら。→ MCP

5つ目は「これを他人にも配るか」——配るなら plugins。混同しやすいのはQ1とQ2、CLAUDE.md・Skills・hooks です。どれも同じに見えますが、違うのはいつ読まれるか・誰が実行するかです。

CLAUDE.md ― 読み込みと遵守を分けて考える

CLAUDE.md は、読み込み対象の場所に置くことで、セッションごとにプロジェクトの前提を渡すファイルです。全プロジェクト共通なら ~/.claude/CLAUDE.md を使えます。文章による指示であって、操作権限を強制する設定ではありません。

「読んだと言うのに守らない」ときは、次の3点を分けて見ます。

読み込まれたか——/context のMemory filesにCLAUDE.mdとルールが出ているかを見ます。起動場所や除外設定によって対象が変わります。直接読み込みされたAGENTS.mdはこの一覧に出ないため、一覧にないだけで未読とは断定できません
圧縮後に戻ったか——プロジェクトルートのCLAUDE.mdは /compact 後にディスクから再読み込み・再注入されます。サブディレクトリのCLAUDE.mdとパス指定ルールは、対象ファイルを読むときに再読み込みされます。会話だけに残した決定とは扱いが違います
行動に反映されたか——読み込まれていても、曖昧な規則や競合する指示は別に点検します。新しい指示が常に勝つ、と時系列だけで判断せず、適用範囲と例外の条件を明記します

公式の目安はCLAUDE.mdを1ファイル200行未満にすること。読み込みの打ち切り位置でも、遵守を保証する境界でもありません。毎回必要な規則を残し、詳細には読む条件を添えて分離します。@path で全部インポートすれば起動時の文脈量は減らないので、必要時だけ使う手順はSkills、対象限定の規則はパス指定ルールへ分けます。

根拠は公式のメモリ仕様です。見分け方の実例とツール別の違いは、AIがルールを無視するときの確認手順にまとめています。

「読みました」は遵守の証拠ではありません。 読み込み表示と、差分・テスト結果をそれぞれ確認します。機械で判定できる条件は次の節のhooksやCIへ移し、未検査の範囲は残したまま報告します。

hooks ― 条件に応じて検査を実行する

「.env は書き換えないで」と文章で頼んでも、遵守率を保証できません。操作前に条件を検査して止める必要があるなら、権限設定とhooksを検討します。

ここでは、hooksのうちシェルコマンドを実行するcommand型を扱います。有効な設定が対象イベントと条件に一致すると、Claude Code本体が起動します。モデルに実行を思い出してもらう必要はありません。ただし、設定で無効化されていたり対象外の経路だったりすれば動きません。全体像は Claude Code hooksとはで扱っています。次は代表的な9つのイベントです。全イベントの一覧ではありません。

SessionStart        開始・再開時
UserPromptSubmit    送信直後          ［ブロック可］
PreToolUse          ツール直前＝門番  ［ブロック可］
PostToolUse         ツール成功後＝整形（実行済み操作は戻らない）
Notification        入力待ち・許可待ち
Stop                応答の終わり      ［ブロック可］
SubagentStop        サブエージェント終了［ブロック可］
SessionEnd          セッション終了
PreCompact          圧縮の前          ［ブロック可］

阻止できる対象はイベントごとに異なります。実行前のツール阻止と、応答終了を止めて作業を続けることは別です。PreToolUse で危険な操作を門前払いし、PostToolUse で自動整形する——この2つが定番の入口です。設定は settings.json の "hooks" キーに書き、置き場所でスコープが決まります（~/.claude/＝ユーザー、.claude/＝共有、settings.local.json＝自分だけ）。

では、冒頭の「.env は書き換えないで」を仕組みにしてみます。公式ガイドにある「保護したファイルの編集を止める」例を、.env に絞った形です。用意するのは設定とスクリプトの2つです。

① .claude/settings.json——Edit か Write を呼ぶ直前に、スクリプトを実行させます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

② .claude/hooks/protect-env.sh——編集先のファイル名が .env で始まる（.env.local なども含む）なら止めます。macOS・Linuxでは chmod +x .claude/hooks/protect-env.sh で実行権限を付けます。

#!/bin/bash
# .claude/hooks/protect-env.sh
command -v jq >/dev/null || { echo "jq が見つからないため編集を止めました" >&2; exit 2; }

FILE_PATH=$(jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # Windows の \ を / にそろえる

if [[ "${FILE_PATH##*/}" == .env* ]]; then
  echo "Blocked: $FILE_PATH は .env なので編集しません" >&2
  exit 2
fi
exit 0

構造はイベント名 → マッチャ＋コマンドの配列です。matcher は対象ツール名で、"Edit|Write" は Edit と Write のどちらかに一致します（省略すると全ツール）。フックは標準入力にJSONを受け取り、Edit と Write では tool_input.file_path に編集先の絶対パスが入ります。Windowsではこのパスの区切りが \ なので、スクリプトの中で / にそろえてから比べています。終了コード 2 で止めると、標準エラーの文が拒否の理由として Claude に渡り、Claude はそれを読んで別のやり方を考えます。1 は非ブロッキングのエラー扱いで操作が続くため、止めたいときは 2 を使います。0 は異議なしで、通常の権限確認に進みます。

スクリプトは bash と jq を使います（公式ガイドの例も jq が前提です）。Windowsではフックが Git Bash で実行され、Git Bash が無いと PowerShell で実行されるので、この例には Git Bash が要ります。jq が見つからないときに素通りさせないよう、スクリプトの最初の処理で止める形にしてあります。

フックは制限をきつくできますが、緩くはできません。 許可を返してもプロンプトを省くだけで、拒否ルールが常に優先されます。PreToolUse の拒否は承認をすべて飛ばすモードでも効くので、第5章で緩めた分の底として使えます。

試し方は公式ガイドと同じです。Claude に「.env にコメントを1行足して」と頼むと、編集の前に止まり、Blocked: の文が Claude に返ります。.env 以外のファイルは今までどおり編集できることも、あわせて試します。スクリプトのパスを書き間違えると、Failed with non-blocking status code という通知が出るだけで門は開いたままになるので、この通知にも注意します。なお、この例が止めるのは Edit と Write の2ツールだけで、BashやPowerShellのコマンドによる書き換えは別の経路です。止めたい範囲に合わせて対象を広げます。出力仕様やイベントの違いは公式のHooksガイドにあります。

代償も先に。command型フックはあなたのユーザー権限でシェルコマンドを自動実行し、アカウントが触れるファイルなら変更も削除もできます。公式も、追加する前にすべてのコマンドを読んでテストするよう求めています。信頼できるものだけを設定し、入力は検証すること。設定ファイルを直接編集した変更は通常は自動で反映されます。/hooks で登録を見て、反映されていなければJSONと場所を点検してからセッションを再起動します。

subagents ― 文脈を分けて任せる

テストの全出力や巨大なログ——読み捨てるはずの大量テキストが積み上がると、肝心の前提が押し出されます。subagents はその作業を別のコンテキストで走らせ、結論の要約だけを受け取る仕組みです。通常は独自の文脈・指示・ツール権限で動くため、親から必要な情報を明示して渡します。会話をforkして親の履歴を引き継ぐ実行は例外です（スキルの context: fork とは別です）。報告は要約になるので、必要な根拠や未確認事項も返すように指定します。

分けると効く——広い調査／大量の出力を伴う確認／結論だけあればよい自己完結タスク
分けると損する——逐次処理／頻繁な往復／同じファイルを触る並行作業／1〜2手で終わる修正

標準機能なので設定なしに使えます。定義を足すなら .claude/agents/<名前>.md（共通なら ~/.claude/agents/）に、YAML フロントマターで name / description / tools / model を書きます。管理は /agents、呼ぶなら @agent-<名前>。まずは標準の探索用・計画用・汎用から。

description が呼び出しの鍵です。メインのエージェントはこれを見て委譲するか判断するので、曖昧だと自動選択されにくくなります。何をするか＋いつ使うかを具体的に——同じ罠が Skills にもあります。

紛らわしい Agent Teams は、複数の独立セッションが共有タスクリストで連携する仕組み。実験的なオプトイン・既定では無効（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）。別インスタンスが動くのでトークン消費が大きく、入れ子にもできません。違いは subagentsとAgent Teamsの違いで比較しています。迷ったら単一セッションか subagents。

Skills ― 手順を資産にする

「毎回この手順で」という定型に対し、Skills が優れているのは、必要なときだけ開かれる点です。実体は SKILL.md を中心にしたフォルダ。先頭に name と description、その下に手順を Markdown で書き、reference/ や scripts/ も同梱できます。.claude/skills/（プロジェクト）か ~/.claude/skills/（共通）に置くだけで認識されます。

肝は段階的開示です。通常はスキルの名前と説明の一覧が文脈に入り、本文は自動選択または /スキル名 による明示呼び出しで読み込まれます。補助資料は必要に応じて読みます。説明一覧も文脈を消費し、多数のスキルがあると予算に合わせて説明が短縮・省略されます。具体的な description を書き、実際に呼び出されたかと手順の結果を別々に確かめましょう。書き方は Claude Agent Skillsとはで扱っています。

一行で。CLAUDE.md＝常に読まれる前提、Skills＝自動選択または明示呼び出しで開く手順書、command型hooks＝設定したイベントと条件で実行される処理。

MCP ― 外のシステムに手を伸ばす

MCP（Model Context Protocol）は、DBの現在値や課題管理のチケットなど、外部のデータや操作にアクセスするための規格です。代表的な接続方法は次の2つ。接続方式とエラーの詳細を組み合わせて原因を探します。

ローカル（stdio）——自分のPCでサーバを子プロセスとして起動。実行ファイルのパス、必要な環境変数、サーバのエラー出力が手がかりです
リモート（HTTP）——URLでサーバに接続。URL、ネットワーク、サーバ側のエラー、認証情報が手がかりです

まず /mcp のステータスと詳細を見ます。failed はローカル・リモートの両方で出ます。claude mcp get <名前> の Issue: にHTTPコードやエラー本文があれば、それも読みます。needs authentication は認証、pending approval はプロジェクトサーバの承認を見直す入口です。固定の Authorization ヘッダが接続時に401/403で拒否された場合は、認証の問題でも failed になります。対処は MCPサーバ接続エラーの直し方にまとめました。

共有設定の .mcp.json はプロジェクト直下に置きます。stdioサーバへ渡す変数はサーバごとの env、HTTPの認証は接続先に応じてOAuthや headers を使います。共有ファイルに実際のキーを直書きせず、例えば ${API_KEY} で環境変数を参照します。Claude Code自身の資格情報など、一部の変数名はリモートのURL・ヘッダ内では空になるため、詳しくは公式の展開規則にあります。

ツール定義は既定で必要時に読み込まれます。 ツール検索が有効な通常の構成では、最初に入るのはツール名とサーバの説明です。検索を無効にした構成や非対応環境、alwaysLoad を指定したサーバなどでは先に定義を読み込みます。出力も文脈を使うので、/context で実際の消費を見て、使わないサーバを無効化しましょう。

plugins ― 一式を束ねて配る

スキル、サブエージェント定義、フック、MCP設定を束ねて配れる形にするのが plugins です。個別プラグインのマニフェストを用意する場合は .claude-plugin/plugin.json に置きます。標準配置は、プラグイン自身のルートに skills/・agents/・hooks/hooks.json・.mcp.json。これらを .claude-plugin/ の下に入れないでください。標準配置だけならマニフェストを省略することもできます。

/plugin marketplace add owner/repo   ← カタログを登録する
/plugin install name@marketplace     ← そこから個別に導入する
/plugin list                         ← marketplace経由の導入済み一覧

上はmarketplace経由の基本手順です。カタログ登録だけではプラグインは入りません。/plugin list はこの経路の導入済み一覧で、skillsディレクトリや同期など別経路の全プラグインを列挙するものではありません。スコープは user（自分の全プロジェクト）／project（共有設定）／local（このプロジェクトの自分だけ）。projectでも、外部ソースのプラグインは各メンバーのインストールが必要です。managedは管理者配布で、ユーザーによる設定変更は制限されます。自作の手順は pluginsとmarketplaceとはで扱っています。

プラグインはあなたの権限で任意のコードを実行しうると公式ドキュメントは警告しています。community掲載品にはAnthropicの自動検証と安全性の審査がありますが、意図どおりの動作が保証されるわけではありません。発行元と同梱コード・MCPサーバを確認しましょう。第5章の権限設計が、ここでは他人が書いたコードにも関わります。

何から入れるか ― 順番の話

6つ並べましたが、全部入れる必要はありません。困りごとが無いうちに入れると設定の複雑さだけが増えます。順番は症状から。

毎回同じ説明をしている → CLAUDE.md。特定の作業だけなら Skills へ
書いたのに守られない → 読み込み・適用範囲・衝突を点検。機械で判定できる条件は hooks へ
すぐ文脈が埋まる → 重い調べ物を subagents へ／不要な MCP を無効化
情報にAIが届かない → MCP。1つずつ繋いで、通ったのを見てから次へ
同じ設定を配りたい → plugins。自分で使えているものだけ束ねる
特に困っていない → 何も入れない。それが最良の状態

最後の行は冗談ではありません。拡張は詰まりの原因も増やします——「Claude Code が変だ」の正体が自分で足した層であることは多い。だから第4章の切り分けが先です。

まとめ

選ぶ基準は4つの問い——お願いで足りるか（CLAUDE.md・Skills）／確実に効かせたいか（hooks）／別の文脈に分けたいか（subagents）／外部に繋ぎたいか（MCP）。配るなら plugins
CLAUDE.md は永続的な指示。ルートのファイルはcompact後に再注入されます。短文化だけで遵守を保証せず、読み込みと行動を別々に確かめます
command型hooks は本体が設定した条件で実行します。対象経路と阻止方法を検証し、実行後のフックでは済んだ操作を取り消せないことに注意します
subagents は別コンテキストで働き要約だけ返す。逐次処理や頻繁な往復には向かない
Skills は必要時に本文を開く段階的開示。自動選択用の説明を具体化し、明示呼び出し後も手順の結果を確かめます
MCP は外部にアクセスする規格。/mcp のステータスと接続方式・エラー詳細を合わせて原因を探す
plugins は配布の箱。他人のコードが自分の権限で走るので発行元を確かめる
入れる順番は症状から。困りごとが生まれてから1つずつ

ツールそのものを比べて選ぶ話はAIコーディング実践講座第6章「拡張機能で能力を広げる」にあります。

拡張していくほど消費は増えます。最後に、長く使い続けるための運用を扱います。次の第7章「コストと上限」へ進みましょう。

拡張する ― CLAUDE.md・hooks・subagents・MCP