ai-docs

Extend Claude Code

Properties1
tagsclaude-code, skills, hooks, mcp, subagents, context, plugins

15 min read

一行要約

CLAUDE.md / Skills / subagents / agent teams / MCP / hooks / plugins の使い分けを決める判断ガイドであり、判断軸は「機能の高機能さ」ではなく「agentic loop のどこに刺さるか」と「context をいつ・どれだけ食うか」の2つ。

要点

前提として、Claude Code は「コードを推論するモデル + ファイル操作・検索・実行・Web アクセスの組み込みツール」であり、組み込みツールでほとんどのコーディング作業は足りる。このページが扱うのはその上の拡張レイヤである、と明言されている。

何がどこに刺さるか

拡張agentic loop のどこに刺さるか
CLAUDE.md毎セッション Claude が見る永続 context
Skills再利用可能な知識と、呼び出せるワークフロー
Code intelligencelanguage server 接続。シンボル単位の移動と型エラー
MCP外部サービス・ツールへの接続
Subagents隔離された context で独自のループを回し、要約だけ返す
Agent teams独立した複数セッションを、共有タスクリストと peer-to-peer メッセージで協調させる
Hookslifecycle event で自分のスクリプト / HTTP リクエスト / プロンプト / subagent を走らせる
Plugins / marketplaces上記をまとめて配布する梱包レイヤ

Skills が最も柔軟な拡張と位置づけられている。skill は知識・ワークフロー・指示を書いた markdown ファイルで、/deploy のようなコマンドで呼べるし、Claude が関連を判断して自動で読むこともできる。現在の会話でも、subagent 経由の隔離 context でも走らせられる。

目的から機能を選ぶ表

機能何をするかいつ使うか例
CLAUDE.md毎会話ロードされる永続 contextプロジェクト規約、「常に X せよ」“Use pnpm, not npm. Run tests before committing.”
SkillClaude が使える指示・知識・ワークフロー再利用する内容、参照文書、繰り返す作業/deploy がデプロイ手順を実行 / API docs skill
Subagent要約だけ返す隔離実行 contextcontext 隔離、並列タスク、専門ワーカー大量のファイルを読むが要点だけ返す調査
Agent teams複数の独立セッションを協調並列調査、新機能開発、対立仮説でのデバッグsecurity / performance / tests のレビュアを同時に立てる
Code intelligencelanguage server による移動と診断型付き言語、grep が遅い / 不正確な大規模コードベースファイル全読みせずシンボル定義へ飛ぶ
MCP外部サービス接続外部のデータや操作DB クエリ、Slack 投稿、ブラウザ操作
Hookイベントで発火するスクリプト等必ず走らせたい自動化ファイル編集のたびに ESLint
Artifactセッション出力を非公開の対話 web ページとして公開端末テキストより視覚的に見たい / 共有したい出力調査の進行に応じて更新されるインシデント年表

「いつ足すか」— トリガー駆動で育てる

You don’t need to configure everything up front. すべてを最初から設定しておく必要はない。

最初から全部を設定する必要はなく、それぞれに分かりやすい引き金がある。多くのチームはおよそこの順で足していく。

引き金足すもの
Claude が規約やコマンドを2回間違えたCLAUDE.md に書く
同じプロンプトを毎回打っているuser-invocable な skill にする
同じ手順書を3回目チャットに貼ったskill にする
Claude が見られないブラウザタブからデータをコピーし続けているMCP server として接続する
シンボルの定義・使用箇所を探すのに大量のファイルを読んでいるcode intelligence プラグインを入れる
二度と参照しない出力で会話が溢れているsubagent に回す
頼まなくても毎回起きてほしいhook を書く
2つ目のリポジトリで同じ設定が要るplugin にする

同じ引き金は更新のタイミングでもある。繰り返す間違いやレビュー指摘は、チャットでの一度きりの訂正ではなく CLAUDE.md の編集である。毎回手で直しているワークフローは、改訂が必要な skill である。

紛らわしい組み合わせの見分け方

Skill vs Subagent — skill は「どの context にも読み込める再利用コンテンツ」、subagent は「本会話から分離して走るワーカー」。

観点SkillSubagent
正体再利用可能な指示・知識・ワークフロー独自 context を持つ隔離ワーカー
主な利点context 間で共有できるcontext 隔離。作業は別で進み、要約だけ返る
context window への影響メイン window に加算される独立した window（入出力とも別勘定）
向いている用途参照資料、呼び出すワークフロー大量ファイル読解、並列作業、専門ワーカー

skill は reference（セッション中ずっと使う知識） と action（/deploy のように何かをさせる） に分かれる。両者は組み合わせられる — subagent は skills: フィールドで skill を preload でき、skill は context: fork で隔離 context 実行できる。

CLAUDE.md vs Skill

観点CLAUDE.mdSkill
ロード毎セッション、自動オンデマンド
@path import可可
ワークフロー起動不可可（/<name>）
向く用途「常に X せよ」参照資料、呼び出すワークフロー

Rule of thumb: Keep CLAUDE.md under 200 lines. 目安: CLAUDE.md は200行未満に保て。

膨らんできたら参照コンテンツを skill に移すか、.claude/rules/ に分割する。

CLAUDE.md vs Rules vs Skills — .claude/rules/ は「毎セッション、または該当ファイルを開いたとき」にロードされる中間物。paths frontmatter を持つ rule は該当ファイルを触るときだけ読まれるので context を節約できる。

Subagent vs Agent team

観点SubagentAgent team
context独自 window。結果は呼び出し元に返る独自 window。完全に独立
通信メインエージェントにのみ報告teammate 同士が直接メッセージ
協調メインが全作業を管理共有タスクリストで自己協調
向く用途結果だけが要る絞られた作業議論と協調が要る複雑な作業
トークンコスト低い（要約されて返る）高い（teammate ごとに別 Claude インスタンス）

移行点: 並列 subagent を走らせていて context 上限に当たる、または subagent 同士が通信する必要が出てきたら、agent teams が自然な次段階。 なお agent teams は experimental で既定では無効。

MCP vs Skill — MCP は「接続と認証を肩代わりする、外部システム向けの専用ツール」を与える。skill は「そのツールをうまく使うための知識」を与える。例: MCP が DB に繋ぎ、skill がデータモデル・よく使うクエリ・どのテーブルを使うかを教える。

Hook vs Skill — ここが最も実務的な区別。

観点HookSkill
走るものshell コマンド / HTTP / LLM プロンプト / subagentClaude が読んで従う指示
起動PostToolUse、SessionStart などの lifecycle event/<name> の入力、または description との一致
決定性必ず発火する。引き金が保証されるClaude が解釈する。結果はぶれる
context コスト出力を返さない限りゼロdescription は毎セッション、本体は使用時
向く用途編集後の lint、危険コマンドのブロック、ログ、通知推論が要るワークフロー、参照資料、多段タスク

Put guardrails in hooks. An instruction like “never edit .env” in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement. **ガードレールは hook に置け。**CLAUDE.md や skill に書いた「.env は絶対に編集するな」という指示はお願いであって、保証ではない。編集を止める PreToolUse hook が強制である。

ルールが毎回必ず成立しなければならないなら、prompt の指示ではなく hook にする。

多層定義の解決規則

同じ機能が user / project / plugin / managed の複数レベルに存在するときの挙動が明示されている。ここは種類ごとに規則が違う。

  • CLAUDE.md — 加算的。全レベルが同時に context に寄与する。作業ディレクトリとその上位が起動時にロードされ、サブディレクトリは作業中に読まれる。矛盾は Claude が判断で調停し、より具体的な指示が優先されるのが通常
  • Skills / subagents — 名前で上書き。優先順は skills が managed > user > project、subagents が managed > CLI flag > project > user > plugin。plugin skill は namespace 付き
  • MCP servers — 名前で上書き。local > project > user
  • Hooks — マージ。出所に関係なく、該当イベントの hook はすべて発火する

context コストの理解

Too much can fill up your context window, but it can also add noise that makes Claude less effective; skills may not trigger correctly, or Claude may lose track of your conventions. 多すぎれば context window を埋めるだけでなく、Claude の性能を落とすノイズにもなる。skill が正しく起動しなかったり、Claude が規約を見失ったりする。

context を食い潰す問題だけでなく、ノイズによって skill の発火精度が落ちる / 規約を見失うことが害として挙げられている点が重要。

機能いつロードされるか何がロードされるかcontext コスト
CLAUDE.mdセッション開始全文毎リクエスト
Skills開始時 + 使用時開始時は description、使用時に本体低（description のみ毎リクエスト）
MCP serversセッション開始ツール名のみ。スキーマは要求時まで遅延ツールを使うまで低い
Code intelligence編集後・参照時編集後の診断、シンボル参照時の位置情報低。むしろファイル読解を減らす
Subagentsspawn 時指定 skill 込みの新規 contextメインから隔離
Hooks発火時何もロードしない（外部実行）ゼロ（出力を返さない限り）
  • skill の description は既定でセッション開始時にロードされる。frontmatter に disable-model-invocation: true を置くと Claude から完全に隠れ、手動起動するまで context コストがゼロになる。自分で書いていない skill には settings の skillOverrides で同じことができる
  • 副作用のある skill には disable-model-invocation: true を使うのが推奨。context 節約に加え、自分だけが起動できることを保証できる
  • MCP は tool search が既定で有効なので、待機中のツールの context 消費は最小。/mcp で接続状態とサーバごとのトークンコストを確認できる
  • subagent が起動時に読むもの: エージェント自身の system prompt（Claude Code のフル system prompt ではない）、skills: の全文、CLAUDE.md と git status（ただし組み込みの Explore / Plan エージェントは両方とも読まない）、リードエージェントが prompt で渡した内容。会話履歴も、起動済み skill も継承しない

組み合わせパターン

パターン仕組み例
Skill + MCPMCP が接続を、skill が使い方を与えるMCP が DB 接続、skill がスキーマとクエリパターンを文書化
Skill + Subagentskill が並列作業のため subagent を起動/audit が security / performance / style の subagent を隔離 context で起動
CLAUDE.md + SkillsCLAUDE.md に常時ルール、skill に参照資料CLAUDE.md「API 規約に従え」、skill に API スタイルガイド全文
Hook + MCPhook が MCP 経由で外部操作重要ファイル変更時に Slack 通知

そのまま使える具体例

CLAUDE.md が膨らんだときの分割先:

.claude/rules/          # paths frontmatter で該当ファイル作業時のみロード
CLAUDE.md               # 200行以内に保つ

副作用のある skill を Claude から隠す:

---
name: deploy
description: Runs the production deployment checklist.
disable-model-invocation: true   # /deploy と打つまでロードされない。context コスト 0
---

subagent に skill を preload する / skill を隔離 context で走らせる:

# subagent 側
skills: [api-style-guide, deployment-checklist]
 
# skill 側
context: fork

MCP のトークンコストを確認する:

/mcp

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク