ai-docs

Extend Claude Code

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

原典: Extend Claude Code ／ 日本語版

一行要約

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

要点

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

何がどこに刺さるか

拡張agentic loop のどこに刺さるか
CLAUDE.md毎セッション Claude が見る永続 context
Output stylesそのセッションの全応答について、Claude の役割・口調・応答形式を決める
Skills再利用可能な知識と、呼び出せるワークフロー
Code intelligencelanguage server 接続。シンボル単位の移動と型エラー
MCP外部サービス・ツールへの接続
Subagents隔離された context で独自のループを回し、要約だけ返す
Dynamic workflowsClaude が書いたスクリプトが多数の subagent を回し、1つの結果を返す
Cross-session messaging自分のあるセッションから別のセッションへ Claude がメッセージを届ける
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.”
Output styleセッション全体の役割・口調・応答形式を決める指示毎回の応答で欲しい声・長さ・形式。ソフトウェアエンジニア以外の役割で使うとき組み込みの Concise で短く / 何を聞いても図から答える自作スタイル
SkillClaude が使える指示・知識・ワークフロー再利用する内容、参照文書、繰り返す作業/deploy がデプロイ手順を実行 / API docs skill
Subagent要約だけ返す隔離実行 contextcontext 隔離、並列タスク、専門ワーカー大量のファイルを読むが要点だけ返す調査
Dynamic workflowClaude が書いたスクリプトが多数の subagent を裏で回すsubagent 数本では収まらない仕事、結果を相互検証させたいときコードベース全体の監査を、別のエージェント群が各指摘を検証しながら回す
Cross-session messaging自分のセッション間で Claude がメッセージを届ける作業の途中で互いの発見が要る、自分で動かしている複数セッション片方が「いま入れた変更が、そちらの土台を壊す」と知らせる
Code intelligencelanguage server による移動と診断型付き言語、grep が遅い / 不正確な大規模コードベースファイル全読みせずシンボル定義へ飛ぶ
MCP外部サービス接続外部のデータや操作DB クエリ、Slack 投稿、ブラウザ操作
Hookイベントで発火するスクリプト等必ず走らせたい自動化ファイル編集のたびに ESLint
Artifactセッション出力を非公開の対話 web ページとして公開端末テキストより視覚的に見たい / 共有したい出力調査の進行に応じて更新されるインシデント年表

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

You don’t need to configure everything up front.

すべてを最初から設定しておく必要はない。

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

引き金足すもの
Claude が規約やコマンドを2回間違えたCLAUDE.md に書く
もっと短く / もっと説明して / 同じ形式で、と毎回頼んでいるoutput style を設定する
同じプロンプトを毎回打っている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 を節約できる。

CLAUDE.md vs Output style — どちらも常時効く指示だが、CLAUDE.md は「Claude が知っておくべきこと」、output style は「どう応答するか」。

観点CLAUDE.mdOutput style
持つものプロジェクトについての事実とルール役割・口調・応答形式
切り替え常にロードされる一度に1つだけ有効。いつでも切り替えられる
向く用途ビルドコマンド、規約、「絶対に X するな」短い応答、コードに添える説明、エンジニア以外の役割
  • どのスタイルでも真であること（規約・ビルドコマンド・構成）は CLAUDE.md
  • 応答そのものについてで、また切りたくなるかもしれないもの（長さ・形式・説明量・別の役割）は output style
  • 両立する。 CLAUDE.md はどのスタイルでもロードされたまま。ただしどちらも指示であって強制ではない —— 毎回必ず起きてほしいことは hook にする

Subagent vs Dynamic workflow —— どちらも本会話の外で働くが、次に何を走らせるかを、subagent では Claude がターンごとに決め、workflow ではスクリプトが決める。

  • subagent は Claude が起こすワーカーで、起こした会話に要約を返す。素早く絞られた仕事（調査、主張の検証、1ファイルのレビュー）向き。起動時に名前を付けた subagent 同士はメッセージを送り合える
  • dynamic workflow は Claude が書いたスクリプトが多数の subagent を裏で回して1つの結果を返す。subagent 数本では収まらない仕事や、見る前に指摘を相互検証させたいとき（コードベース全体の監査、大規模移行、複数の角度から起こす計画）
  • 自分の別セッションに発見を渡したいなら、最初のセッションの Claude に送らせる（cross-session messaging）

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セッション開始全文毎リクエスト
Output stylesセッション開始と、スタイルを切り替えたとき有効なスタイルの指示の全文（Default スタイルは何もロードしない）毎リクエスト
Skills開始時 + 使用時開始時は description、使用時に本体低（description のみ毎リクエスト）
MCP serversセッション開始ツール名のみ。スキーマは要求時まで遅延ツールを使うまで低い
Code intelligence編集後・参照時編集後の診断、シンボル参照時の位置情報低。むしろファイル読解を減らす
Subagentsspawn 時指定 skill 込みの新規 context。fork なら親の会話そのものメインから隔離
Hooks発火時何もロードしない（外部実行）ゼロ（出力を返さない限り）
  • skill の description は既定でセッション開始時にロードされる。frontmatter に disable-model-invocation: true を置くと description が Claude の context に入らなくなり、呼ぶまで 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   # 名前を挙げるまでロードされない。context コスト 0
---

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

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

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

/mcp

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

バックリンク