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）。ファイルなので、第1章で見た「長引くと前半を忘れる」の影響を受けません。毎回説明していることの置き場所です。

「読んだと言うのに守らない」は怠慢ではなく構造の問題で、原因は3つあります。

中盤が沈む——長文の中ほどの指示は見落とされやすく、伸ばすほど真ん中のルールは事実上いなくなります
圧縮で要約される——圧縮が走ると細かい運用ルールは潰れます。後半ほど違反が増えるのはこれです
直近の指示が勝つ——「とりあえずコミットして」が、数百ターン前に読んだ確認手順を素通りさせます

対処は削ること。経験則で確実に効くのは100〜150行あたりまで。超えるなら致命的な掟だけ冒頭に残し、詳細は別ファイルへ（重複はズレを生むので正本は1箇所に）。落とせないものだけ「CRITICAL」を付け、「丁寧に書く」ではなく「3行以内で書く」のように外から判定できる形にすること。

「読みました」は証拠になりません。 判断材料は実行後の振る舞いだけ。何度書き直しても守られないルールは、書き方の問題ではありません——次の節の仕事です。

hooks ― お願いではなく、確定的に効かせる

「.env は書き換えないで」——CLAUDE.md に書けば9割は守られます。1割抜けても困らないなら文章で足りる。困るなら hooks——これが分岐点です。

hooks は決まった時点で自動実行されるシェルコマンドです。走らせるのがモデルではなく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＝自分だけ）。

{ "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [ { "type": "command", "command": "..." } ] }
    ] } }

構造はイベント名 → マッチャ＋コマンドの配列。matcher は対象ツール名（"Edit|Write" のように | 区切り、省略で全一致）。フックは標準入力にJSONを受け取り、終了コードで返します——0 が成功、2 がブロック（標準エラー出力が Claude に渡ります）。対象のファイルパスも入力JSONから取れるので「このパスなら止める」が書けます。

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

代償も先に。hooks はあなたの権限で任意のシェルコマンドを自動実行します。公式も「責任は完全にあなたにある」と明記しています。信頼できるものだけを設定し、入力は検証すること。設定はセッション開始時に固定されるので、「直したのに効かない」ときは新しいセッションを開いてください。

subagents ― 文脈を分けて任せる

テストの全出力や巨大なログ——読み捨てるはずの大量テキストが積み上がると、肝心の前提が押し出されます。subagents はその作業を別のコンテキストで走らせ、結論の要約だけを受け取る仕組みです。独自のコンテキストウィンドウ・システムプロンプト・ツール権限を持ち、あなたの会話履歴を見ていないので、調べ物の残骸がメインに戻ってきません。

分けると効く——広い調査／大量の出力を伴う確認／結論だけあればよい自己完結タスク
分けると損する——逐次処理／頻繁な往復／同じファイルを触る並行作業／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.md との決定的な差です。裏返しに合致しないと一生開かれません。description が曖昧なら、書いた手順は存在しないのと同じ。書き方は Claude Agent Skillsとはで扱っています。

一行で。CLAUDE.md＝常に読まれる前提、Skills＝Claude が判断して開く手順書、hooks＝必ず走る処理。

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

ここまでの3つはやり方を変える拡張でした。MCP（Model Context Protocol）だけは触れる範囲を広げます——DBの現在値や課題管理のチケットのように、AIが構造的に知りようのないものへ手を届かせる規格です。接続の形は2つで、詰まる場所が違います。

ローカル（stdio）——自分のPCでサーバをサブプロセスとして起動。詰まるのは起動そのもの（パス、環境変数、コマンド解決）
リモート（HTTP）——クラウド上のサーバに URL で接続。詰まるのはほぼ認証＝401 や 403 が返っている状態

だから「繋がらない」を一括りにせず、まず /mcp でステータスを見ます。failed ならローカル起動、needs authentication ならリモートの認証、pending approval なら承認待ち——ステータスが打ち手を決めます。対処は MCPサーバ接続エラーの直し方にまとめました。

特有の罠も。共有設定の .mcp.json はリポジトリ直下（.claude/ の下でも settings.json の中でもありません）、APIキーはサーバごとの env に。Windows では npx の実体がバッチファイルのため、cmd 経由で /c npx ... と渡すと通ります。

繋いだサーバはコンテキストを消費します。 ツール定義が積み上がるだけで文脈が圧迫されます。使っていないサーバは無効化しておくのが無難です。

plugins ― 一式を束ねて配る

スキル、サブエージェント定義、フック、MCP 設定が散らばってきたら、束ねて配れる形にするのが plugins です。間違えやすいのはディレクトリ規則。マニフェストは .claude-plugin/plugin.json で、.claude-plugin/ に入れるのはそれだけ。skills/・agents/・hooks/hooks.json・.mcp.json はルートに置きます。

/plugin marketplace add owner/repo   ← カタログを登録する
/plugin install name@marketplace     ← そこから個別に導入する
/plugin list                         ← 入っているものを確認する

導入は2段階。カタログを登録し、そのうえで個別にインストール——追加しただけでは何も入りません。スコープは user（全プロジェクト）／project（共同作業者全員）／local（自分だけ）／managed（管理者配布・変更不可）で、チームで揃えるなら project。自作の手順は pluginsとmarketplaceとはで扱っています。

プラグインはあなたの権限で任意のコードを実行しうる——公式ドキュメントの明記です。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 はセッションをまたぐ記憶。長くすると中盤が沈み、圧縮で薄まり、直近の指示に負ける。削って優先度を明示する
hooks はハーネスが実行するので判断が入らない。制限はきつくできるが緩くはできない
subagents は別コンテキストで働き要約だけ返す。逐次処理や頻繁な往復には向かない
Skills は description が合致したときだけ開く段階的開示。増やしても軽いが、説明が曖昧だと呼ばれない
MCP は触れる範囲を広げる規格。/mcp のステータスで打ち手が決まる
plugins は配布の箱。他人のコードが自分の権限で走るので発行元を確かめる
入れる順番は症状から。困りごとが生まれてから1つずつ

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

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