【完全版活用ガイド】Claude Code拡張機能の全体像を知る

Last updated at 2026-03-06Posted at 2026-03-01

はじめに

Claude Codeは対話するだけでも十分に活用できる。しかし5つの拡張機能を使いこなすことで、開発の質と速度が大きく向上する。この記事では、CLAUDE.md / Skills / Subagents / Hooks / MCP Serversの5機能を、設計意図から実運用パターンまで体系的に解説する。「この記事だけで拡張機能のほぼ全体像を掴める」ことを目指した。

この記事でわかること

CLAUDE.mdが「何を解決するのか」と設置場所の使い分け
Skillsで知識・手順をオンデマンドにロードする方法
Subagentsでコンテキストを分離して並列作業する設計
Hooksでイベント駆動の自動化パイプラインを組む手順
MCP Serversで外部システムとの接続を標準化する仕組み
5機能を組み合わせたPlugin的アーキテクチャの構築法

想定読者

Claude Codeを日常的に使っている中級者を想定している。基本操作は理解しているが、拡張機能は断片的にしか把握できていない方が対象となる。

5機能の全体関係図

5つの拡張機能は、それぞれ異なる役割を持つ。以下の図でその関係を俯瞰していただきたい。

読み方ガイド

各章は独立して読める構成にしている。目次から興味のある機能へジャンプしていただきたい。最後の「実践アーキテクチャ」章で5機能の組み合わせ方を解説しているので、全体像を先に知りたい方はそちらから読んでもよい。

1. CLAUDE.md ── 常時ロードされる永続コンテキスト

1-1. 役割

CLAUDE.mdは「毎セッション開始時に読み込まれる永続コンテキスト」である。設計原則やコーディング規約、禁止事項、標準コマンドなど、常に効かせたいルールをここに記述する。

セッションをまたいでも必ず適用される点が最大の利点となる。プロンプトで毎回指示を繰り返す手間がなくなり、チーム全員が同じルールで作業できる。逆に言えば「毎回読み込まれても邪魔にならない情報」だけを厳選する必要がある。

1-2. どこに置くか（スコープ）

CLAUDE.mdには6つの配置場所がある。スコープが異なるため、影響範囲を意識して使い分ける。

スコープ	パス	用途
組織管理	`/Library/Application Support/ClaudeCode/CLAUDE.md`（macOS）	全社共通のガバナンスルール
ユーザー共通	`~/.claude/CLAUDE.md`	個人の横断的スタイル設定
ユーザールール	`~/.claude/rules/*.md`	個人ルールのトピック分割
プロジェクト	`./CLAUDE.md` または `./.claude/CLAUDE.md`	リポジトリ固有の規約
プロジェクトルール	`./.claude/rules/*.md`	プロジェクトルールのトピック分割
ローカル個人	`CLAUDE.local.md`	個人環境固有の設定（gitignore対象）

組織管理パスはOSごとに異なる。Linuxでは/etc/claude/CLAUDE.md、WindowsではAppDataパス配下に配置する。

この階層構造により「組織→個人→プロジェクト→ローカル」と段階的にルールを重ねられる。組織で大枠を定め、プロジェクトで具体化し、個人で微調整するイメージである。

1-3. 読み込み順と優先順位

CLAUDE.mdの読み込みには明確な順序がある。理解しておかないと「設定したのに反映されない」トラブルの原因になる。

起動時、Claude Codeは作業ディレクトリから上位ディレクトリへと辿り、見つかったCLAUDE.mdとCLAUDE.local.mdをすべて読み込む。サブディレクトリ配下のCLAUDE.mdは、そのディレクトリ内のファイルを操作するタイミングでオンデマンドに読み込まれる。

優先順位は「より具体的なスコープが勝つ」ルールで決まる。プロジェクトレベルの指示はユーザーレベルより強く、ローカルはプロジェクトより強い。.claude/rules/は.claude/CLAUDE.mdと同等レベルで読み込まれる。

1-4. @importを使った分割運用

CLAUDE.mdが肥大化すると可読性が下がる。@importを使えば外部ファイルに分割しつつ、1つのコンテキストとして取り込める。

# CLAUDE.md
@docs/coding-style.md
@docs/api-conventions.md

パス解決には注意が必要である。相対パスは「作業ディレクトリ基準」ではなく「importを書いたファイルの場所基準」で解決される。例えば.claude/CLAUDE.mdに@../docs/style.mdと書いた場合、プロジェクトルート直下のdocs/style.mdを参照する。

importは最大5ホップまで再帰する。AがBをimportし、BがCをimportする連鎖が5段階まで追跡される。それ以上はループ防止のため無視される。

コードスパンやコードブロック内の@...はimportとして解釈されない。ドキュメント内でimport構文を説明するときも安心して記述できる。

初回の外部importではプロジェクト単位で承認ダイアログが表示される。意図しないファイルの読み込みを防ぐセキュリティ機構である。

複数のworktreeで同じ個人設定を共有したい場合は、@~/.claude/shared-rules.mdのようにホームディレクトリ基準のimportが有効に機能する。

1-5. /memoryでの実務運用

/memoryコマンドは、CLAUDE.mdとAuto memoryを直接開いて編集できるショートカットである。

読み込まれたメモリの一覧確認にも使える。「今どのCLAUDE.mdが有効なのか」を手早く把握したいときに重宝する。Auto memoryの有効・無効も/memoryからトグルで切り替えられるため、一時的にAuto memoryを停止したい場合にも使う。

1-6. .claude/rules/によるモジュール化

大規模プロジェクトではCLAUDE.md 1枚に全ルールを詰め込むと管理が破綻する。.claude/rules/ディレクトリでトピックごとにファイルを分割するほうが運用しやすい。

1ファイル1トピックを基本にする。例えばtesting.md、api-design.md、security.mdのように分ける。サブディレクトリの再帰読み込みにも対応しているので、rules/frontend/とrules/backend/で領域別に整理することも可能である。

シンボリックリンクに対応している点も見逃せない。共通ルールファイルを1箇所に置き、複数リポジトリからシンボリックリンクで参照すれば、ルールの一元管理ができる。

pathsフロントマターを使えば、特定パスのファイルを操作するときだけルールを適用する条件付きルールを設定できる。

---
paths:
  - "src/api/**/*.ts"
---

## API設計ルール

- レスポンスは必ずResult型でラップする
- エラーコードはerror-codes.tsの定義を使う

この設定ではsrc/api/配下のTypeScriptファイルを扱うときだけ、このルールが有効になる。

1-7. Auto Memoryの制御ポイント

Auto Memoryは作業中にClaude自身が学習した事実を自動保存する機能である。制御方法を把握しておかないと、意図しない情報がコンテキストに混入する。

保存先: ~/.claude/projects/<project>/memory/
起動時読み込み: MEMORY.mdの先頭200行のみ自動で読み込まれる
200行超の詳細: topicファイルへ分離し、必要時にオンデマンド読み込みされる
全体無効化: ~/.claude/settings.jsonで"autoMemoryEnabled": falseを設定する
プロジェクト単位の無効化: .claude/settings.jsonで同じ設定を記述する
環境変数での強制制御: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1で無効化できる（CI環境向き）

環境変数による制御はCI/CDパイプラインや管理環境で便利である。設定ファイルを変更せずに挙動を上書きできる。

1-8. --add-dir利用時の注意

claude --add-dir <dir>で追加ディレクトリを指定しても、そのディレクトリのCLAUDE.mdはデフォルトでは読み込まれない。この仕様を知らないと「設定したはずのルールが効かない」という混乱が生じる。

追加ディレクトリのCLAUDE.mdも読み込ませるには、環境変数を設定する。

export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1

共有設定ディレクトリを横断的に利用するプロジェクトでは、この設定を.bashrcや.zshrcに入れておくとよい。

1-9. Auto Memoryとの役割分担

Claude Codeには2種類の記憶がある。混同しやすいので明確に区別しておく。

種類	書き手	内容	読み込みタイミング
CLAUDE.md	人間	設計原則・コーディング規約・禁止事項	毎セッション全量読み込み
Auto Memory	Claude	作業中に学習した事実・プロジェクト固有情報	MEMORY.md先頭200行のみ自動読み込み

CLAUDE.mdは全体が読み込まれるため、長文化するとトークンを消費してノイズになりやすい。一方、Auto Memoryは200行制限があるため、溢れた情報はtopicファイルに分離される。

実運用では「方針・ルール → CLAUDE.md」「事実・学習結果 → Auto Memory」と棲み分けるのが安定する。

1-10. 設計観点

CLAUDE.mdの内容を設計するとき、3つの観点で整理すると散らかりにくい。

ガバナンス: 「必ず守る」方針はCLAUDE.mdに置く。セキュリティポリシーや命名規約など、例外を許さないルールが該当する。

再現性も重要な観点となる。ビルドコマンド、テスト実行方法、開発サーバーの起動コマンドを明示しておくと、Claudeが正しい手順で作業を進められる。

省トークンの意識も欠かせない。200行前後を目安に要約し、詳細は.claude/rules/やimportで分離する。毎回読み込まれるファイルだからこそ、簡潔さが価値を持つ。

1-11. 実運用パターン

実際のプロジェクトでは以下のように役割を分散させると管理しやすい。

置き場	内容	例
CLAUDE.md	コア規約	コーディングスタイル、禁止パターン
.claude/rules/	領域別規約（pathsで条件適用）	api-design.md、testing.md
Skills	タスク手順	デプロイ手順、リリースフロー
CLAUDE.local.md または @~/.claude/... import	個人の癖・好み	エディタ設定、出力スタイル
Auto Memory	頻繁更新の情報	依存ライブラリのバージョン、既知の不具合

CLAUDE.mdには方針を、Auto Memoryには事実を寄せるのがポイントである。頻繁に変わる情報をCLAUDE.mdに書くと、メンテナンスコストが跳ね上がる。

1-12. よくある失敗

何でもCLAUDE.mdに詰め込む
CLAUDE.mdは毎回全量読み込まれる。デプロイ手順やトラブルシュート集まで入れると、トークンを圧迫してClaude の応答品質が落ちる。常時必要なルールだけに絞り、手順はSkillsへ、詳細は.claude/rules/へ分離する。

ディレクトリ固有ルールを全体ルールに混ぜる
フロントエンド固有のルールをプロジェクトルートのCLAUDE.mdに書くと、バックエンド作業時にもノイズとして読み込まれる。.claude/rules/のpathsフロントマターで適用範囲を限定する。

タスク手順を常時ロードさせる
デプロイ手順やマイグレーション手順は実行頻度が低い。Skillsに分離してオンデマンド呼び出しにするほうがトークン効率がよい。

pathsを乱用して判定が複雑化する
条件付きルールが増えすぎると、どのルールが有効なのか把握しづらくなる。pathsは「明確に領域が分かれている場合」に限定して使う。

--add-dir利用時に共有メモリが読まれない
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1の設定漏れに気づかないケースが多い。--add-dirを使うなら、この環境変数の設定をセットで確認する。

2. Skills ── 必要なときだけロードされる知識と手順

2-1. 役割

Skills は「必要なときだけロードされる知識・手順・ワークフロー」を担う仕組みである。
CLAUDE.md が常時読み込みの永続コンテキストであるのに対し、Skills は呼ばれるまでコンテキストを消費しない。
/skill-name で明示的に実行でき、description の内容次第で Claude が自動適用することもできる。

常に読み込まれる CLAUDE.md にタスク手順を詰め込むと、トークンを無駄に消費する。
手順やドメイン知識はSkillに分離し、必要なときだけ読み込ませるのが基本方針となる。

2-2. 配置場所と優先順位

Skills は4つのスコープに配置できる。

スコープ	パス	効果範囲
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	全プロジェクト共通
Project	`.claude/skills/<skill-name>/SKILL.md`	そのリポジトリのみ
Enterprise	組織管理設定で配布	組織全体
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	プラグイン利用者

同名のスキルが複数スコープに存在する場合、優先順位は次のとおりになる。

enterprise > personal > project

Plugin スキルは plugin-name:skill-name という名前空間を持つ。
この仕組みにより、他スコープのスキルとの名前衝突を回避できる。

スコープの使い分けには明確な指針がある。
個人の作業効率化は Personal、チーム規約は Project、統制が必要な手順は Enterprise に置く。

2-3. 発見と読み込み（モノレポ向け）

モノレポ構成ではパッケージごとに異なるスキルが必要になる場合がある。
Claude Code はネストされた .claude/skills/ ディレクトリを自動検出する。

たとえば以下のように配置すると、packages/frontend/ 配下の作業時に自動で候補に上がる。

monorepo/
├── .claude/skills/shared-review/SKILL.md   ← 全体共通
├── packages/
│   ├── frontend/.claude/skills/ui-gen/SKILL.md  ← frontend作業時のみ
│   └── backend/.claude/skills/api-gen/SKILL.md  ← backend作業時のみ

--add-dir で追加したディレクトリ内のスキルも自動読み込みの対象になる。
ただし --add-dir 側の CLAUDE.md を読み込ませるには、別途 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 の設定が必要である。
スキルは自動で見えるが CLAUDE.md は見えない、という非対称性に注意していただきたい。

2-4. SKILL.md の構造

1つのスキルはディレクトリ単位で管理する。
ディレクトリ内の SKILL.md が必須のエントリポイントになる。

SKILL.md は「YAML frontmatter + 本文指示」の2パートで構成する。

---
name: review-pr
description: >
  Pull Requestの差分を読み取り、
  コード品質・セキュリティ・パフォーマンスの観点でレビューする。
---

## レビュー手順

1. `gh pr diff` で差分を取得する
2. 変更ファイルごとに以下の観点で確認する
   - 命名規約の遵守
   - エラーハンドリングの漏れ
   - パフォーマンス上の懸念
3. 指摘事項をまとめて出力する

frontmatter の中で最も重要なフィールドは description である。
Claude が「このスキルを自動適用すべきか」を判断する材料として使うためである。
name は省略するとディレクトリ名がそのまま slash command 名になる。

2-5. スキルコンテンツの2タイプ

Skills の内容は大きく2タイプに分かれる。

リファレンス型 は規約・設計方針・ドメイン知識をまとめたスキルである。
Claude が関連する作業を検知したとき、インラインで自動適用される。
たとえば「APIのエラーレスポンス形式」や「DB命名規約」などが該当する。

タスク型 はデプロイ・コミット・コード生成など、具体的な手順を実行するスキルである。
多くの場合 /skill-name で手動実行する使い方が適している。

タスク型で副作用（ファイル変更、API呼び出し、デプロイなど）がある場合は、disable-model-invocation: true を設定するのが基本である。
Claude の自動判断による意図しない実行を防ぐためである。

---
name: deploy
description: ステージング環境へのデプロイを実行する。
disable-model-invocation: true
---

2-6. frontmatter 実務リファレンス

SKILL.md の frontmatter で使えるフィールドの全一覧を示す。

フィールド	型	用途
`name`	string	slash command 名。省略時はディレクトリ名
`description`	string	自動適用判定の最重要フィールド
`argument-hint`	string	`/skill-name` 実行時の引数ヒント表示
`disable-model-invocation`	bool	Claude の自動呼び出しを禁止
`user-invocable`	bool	ユーザーメニューへの表示を制御
`allowed-tools`	list	スキル実行中に許可するツール
`model`	string	実行に使うモデルの指定
`context`	string	`fork` で分離コンテキスト実行
`agent`	string	使用する Subagent の指定
`hooks`	object	スキル実行前後のフック定義

運用上の整備順序は次のとおりである。

まず description を書く。自動適用の精度がここで決まる
次に disable-model-invocation で副作用スキルを保護する
allowed-tools で利用ツールを最小限に絞る
必要に応じて context や agent で実行形態を調整する

2-7. 呼び出し制御（重要）

スキルの呼び出し方を制御する設定は2つある。
組み合わせにより3パターンの挙動が生まれる。

設定	ユーザー呼び出し	Claude 自動呼び出し	description の常時ロード
デフォルト	可	可	あり
`disable-model-invocation: true`	可	不可	なし
`user-invocable: false`	不可	可	あり

この表で見落としやすいのは user-invocable: false の挙動である。
これはスラッシュコマンドメニューへの表示を抑制するだけであり、Claude 側の自動呼び出しは止まらない。
「Claude に勝手に呼ばれたくない」場合は disable-model-invocation: true を使う必要がある。

以下のデシジョンツリーで使い分けを判断できる。

user-invocable: false を「安全装置」として使うのは適切ではない。
モデルからの呼び出しを確実に止めるには disable-model-invocation: true が唯一の手段となる。

2-8. 引数と文字列置換

スキルには実行時に引数を渡せる。
本文中で以下のプレースホルダを使って引数を参照する。

プレースホルダ	内容
`$ARGUMENTS`	全引数をまとめた文字列
`$ARGUMENTS[N]` / `$N`	N 番目の引数（位置指定）
`${CLAUDE_SESSION_ID}`	現在のセッション ID

${CLAUDE_SESSION_ID} はログファイル名にセッションを紐付けたい場合に有用である。

---
name: gen-component
description: React コンポーネントを生成する。
argument-hint: "<component-name> [--with-test]"
---

## 指示

コンポーネント名: $1
オプション: $ARGUMENTS

上記に基づいて src/components/ 配下にファイルを生成せよ。

$ARGUMENTS を本文に明示的に書かなくても、入力値は ARGUMENTS: ... として本文末尾に自動付与される。
プレースホルダを書くのは、引数を本文の特定箇所に埋め込みたいときだけでよい。

2-9. サポートファイル分割

SKILL.md が肥大化するとコンテキストを圧迫し、指示の精度が落ちる。
以下の構成で役割を分離するのが推奨パターンである。

.claude/skills/review-pr/
├── SKILL.md          ← 概要と意思決定ロジックのみ
├── reference.md      ← 詳細な仕様・規約
├── examples.md       ← 入出力の具体例
└── scripts/
    └── collect-diff.sh  ← 実行ヘルパースクリプト

SKILL.md は500行以下を目安に保つ。
500行を超えるようなら、詳細を reference.md や examples.md に切り出す。
SKILL.md 本文から Read ツールで外部ファイルを読ませる指示を書けば、必要時にだけ詳細を参照させられる。

分離の判断基準は「SKILL.md を読んだだけで何をすべきか分かるか」である。
意思決定に不要な詳細データは外部に出す。

2-10. 高度なパターン

動的コンテキスト注入

スキル送信前にコマンドを実行し、その結果を本文へ展開できる。
!`command` 記法を使う。

---
name: summarize-pr
description: 現在のPRを要約する。
---

## PR の差分

!`gh pr diff`

## PR の情報

!`gh pr view`

## 指示

上記の差分と情報をもとに、変更内容を3行で要約せよ。

この仕組みにより、スキル実行時点の最新情報をコンテキストに含められる。
静的な SKILL.md だけでは対応しにくい「直前の状態に基づく判断」が可能になる。

拡張思考の活用

スキル本文に ultrathink というキーワードを含めると、Claude は拡張思考モードで処理する。
複雑な判断を伴うスキルで精度を上げたい場合に有効である。

2-11. Subagents 連携（ワークフロー中核）

Skills と Subagents の連携には2つの方向がある。

方向1: Skill から Subagent を起動する。
Skill の frontmatter で context: fork と agent を指定する。
スキル実行時に分離コンテキストで Subagent が起動し、完了後に要約がメイン会話へ返る。

---
name: deep-review
description: コードベース全体を探索してレビューする。
context: fork
agent: explore
allowed-tools:
  - Read
  - Grep
  - Glob
---

## タスク

リポジトリ全体を探索し、以下の観点でレビューせよ。
- 未使用の依存パッケージ
- エラーハンドリングの欠落
- テストカバレッジの薄い領域

方向2: Subagent 側からスキルを読み込む。
Subagent 定義の skills フィールドに指定することで、起動時にスキルをプリロードできる。
Subagent が特定の知識や手順を前提に動く場合に使う。

# .claude/agents/frontend-worker.md の frontmatter
---
skills:
  - ui-gen
  - component-test
---

context: fork を使う場合、SKILL.md の本文に具体的なタスク指示が必須である。
ガイドラインや規約だけを書いたスキルを fork 実行しても、Subagent は「何をすればよいか」が分からず空振りする。
fork 実行するスキルには必ず「何を調べ、何を出力するか」を明記する。

2-12. 権限と安全設計

スキルが利用できるツールは allowed-tools で制限できる。
これにより、意図しないファイル変更やコマンド実行を防げる。

---
name: readonly-review
description: コードを読み取り専用でレビューする。
allowed-tools:
  - Read
  - Grep
  - Glob
---

組織や個人の権限設定（/permissions）では、Skill(...) 単位で許可・拒否を指定できる。

# 権限設定の例
allow: Skill(commit)
allow: Skill(review-pr *)
deny:  Skill(deploy *)

ワイルドカード * を使えば引数パターンごとの制御も可能である。
たとえば Skill(deploy *) を deny にすれば、deploy スキルのあらゆる引数パターンでの実行を拒否できる。

なお、/init や /memory などの組み込みコマンドはスキルツール経由で呼び出すことができない。
これらは Claude Code 本体の機能であり、スキルの権限系とは別の仕組みで動作する。

2-13. 共有方法

スキルの共有方法は配布先に応じて3つある。

共有先	方法	適するケース
プロジェクトチーム	`.claude/skills/` をリポジトリにコミット	チーム固有の手順・規約
外部配布	プラグインの `skills/` ディレクトリとして配布	OSS ツールやフレームワーク向け
組織全体	管理設定（Enterprise）で配布	統制が必要なワークフロー

プロジェクト共有はもっとも手軽である。
.claude/skills/ ディレクトリをコミットするだけで、チーム全員が同じスキルを使える。
レビューフローに乗るため、スキルの変更も通常のコード変更と同じように管理できる。

2-14. 実運用ユースケース

4つの代表的なパターンを示す。

ケース1: デプロイ系の手動専用スキル

デプロイ・リリース・DBマイグレーションなど副作用の大きい操作は、Claude の自動判断で実行されると危険である。
disable-model-invocation: true を設定し、必ずユーザーの明示的な /deploy で実行させる。

---
name: deploy
description: ステージング環境へデプロイを実行する。
disable-model-invocation: true
argument-hint: "<environment>"
allowed-tools:
  - Bash(deploy.sh *)
---

ケース2: 背景知識スキル

レガシーシステムの仕様や業務ドメインの用語集など、Claude が作業中に自動参照すべき知識をスキル化する。
user-invocable: false を設定すると、ユーザーのメニューには表示されないが、Claude は必要に応じて自動で読み込む。

---
name: legacy-system-context
description: >
  旧基幹システム（COBOL時代）のテーブル構造と
  データフロー仕様。移行作業時に参照する。
user-invocable: false
---

ケース3: PR 要約スキル

context: fork で分離実行し、gh コマンドで PR 情報を取得して要約する。
Explore エージェントを指定することで読み取り中心の高速処理になる。

---
name: summarize-pr
description: 現在のPRを要約する。
context: fork
agent: explore
allowed-tools:
  - Bash(gh pr *)
  - Bash(gh api *)
  - Read
  - Grep
---

ケース4: 読み取り専用レビュースキル

allowed-tools を Read, Grep, Glob に限定する。
ファイルの変更やコマンド実行ができないため、安全にコードレビューを任せられる。

---
name: safe-review
description: コードベースを読み取り専用でレビューする。
allowed-tools:
  - Read
  - Grep
  - Glob
---

2-15. よくある失敗

以下のミスはスキル運用でよく見かけるパターンである。設計時に確認していただきたい。

副作用タスクを自動呼び出し可能のままにする。
デプロイやDB操作など外部に影響を与えるスキルは、必ず disable-model-invocation: true を設定する。デフォルトのままだと、Claude が文脈から「実行すべき」と判断して自動実行する可能性がある。

user-invocable: false だけで安全性を担保したと誤解する。
2-7節で述べたとおり、この設定はメニュー非表示にするだけである。Claude の自動呼び出しは止まらない。安全制御には disable-model-invocation: true を使う。

SKILL.md に重い資料を詰め込み続ける。
500行を超える SKILL.md はコンテキストを圧迫し、指示の遵守率が下がる。詳細は reference.md や examples.md に分離する。

context: fork にタスク指示がなく空振りさせる。
fork で起動された Subagent は、本文のタスク指示を頼りに動く。ガイドラインや規約だけを書いた SKILL.md を fork 実行しても、「何をすべきか」が不明なため有効な出力が得られない。

3. Subagents ── 分離されたコンテキストで動く作業者

3-1. 役割

Subagent はメイン会話から分離された実行コンテキストで動く作業者である。大量のログ出力や試行錯誤の探索過程を隔離し、要約だけをメイン会話へ返す。

メイン会話のトークン枠を守りながら重い作業を委任できる点が最大の価値になる。巨大な grep 結果やテスト出力をメインに流すと文脈が埋まるが、Subagent に任せればその問題を回避できる。

3-2. いつ Subagent を使うべきか

Claude Code には Subagent 以外にも Skill やメイン会話という選択肢がある。公式の使い分けは次の通りである。

複数観点の並列調査が必要な場合 → Subagent を使う
ワークフロー手順の標準化が目的 → Skill を使う
会話しながら1つずつ詰める探索 → メイン会話で進める

Subagent は「隔離と並列化」が価値になる場面で最も力を発揮する。逆に、対話的なやり取りが中心ならメイン会話の方が効率的である。

3-3. 組み込みエージェント

Claude Code にはあらかじめ用意された組み込みエージェントがある。カスタムエージェントを作る前に、まずこれらで要件を満たせないか確認するとよい。

エージェント名	用途
`general-purpose`	汎用。コード検索・編集・コマンド実行を一通りこなす
`explore`	読み取り中心の高速探索向き。書き込み系ツールを持たない
`plan`	plan mode 向け。計画立案に特化した構成

上記以外にもサポート用途の組み込みエージェントが環境によって表示される。/agents メニューで現在利用可能な一覧を確認できる。

3-4. 作成・管理方法

カスタム Subagent を作る方法は3つある。

対話 UI: /agents で作成・編集する。frontmatter の雛形が自動生成されるため、初回はこちらが推奨である。
ファイル直接編集: .claude/agents/*.md または ~/.claude/agents/*.md に Markdown ファイルを配置する。Git 管理したい場合に適している。
CLI 追加: --agents <path> で任意ディレクトリを指定して読み込ませる。モノレポや共有ライブラリでの運用に便利である。

3-5. 配置場所と優先順位

同名のエージェントが複数の場所に存在する場合、以下の優先順位で解決される。

--agents で指定したパス（最優先）
プロジェクト: .claude/agents/
ユーザー: ~/.claude/agents/
プラグイン同梱エージェント（最低優先）

プロジェクト固有の挙動を上書きしたい場合は --agents が最も確実である。チーム共有のエージェントはプロジェクト配置、個人用はユーザー配置に分けるとよい。

3-6. frontmatter 設計（中核）

Subagent の .md ファイルは YAML frontmatter と本文指示で構成する。frontmatter がエージェントの振る舞いを決定する中核部分である。

主要な設定項目を以下に整理する。

カテゴリ	項目
基本情報	`name`, `description`, `model`
ツール制御	`tools`, `allowedTools`, `disallowedTools`
外部連携	`mcpServers`, `skills`
実行制御	`permissionMode`, `maxTurns`, `settings`
記憶	`memory`（`scope: none\|project\|user\|local`）
イベント	`hooks`
動作モード	`background`（`foreground\|background`）
環境分離	`isolation`（`workspace-write\|read-only\|danger-full-access`）

以下は読み取り専用レビュー用エージェントの最小構成例である。

---
name: code-reviewer
description: PR の変更点を読み取り専用でレビューする
model: sonnet
tools: Read, Grep, Glob
permissionMode: default
maxTurns: 8
memory:
  scope: project
background: foreground
---

変更意図、潜在バグ、テスト不足を報告する。

tools で許可ツールを最小限に絞り、maxTurns で暴走を防止している。memory.scope: project により、レビューで得た知見をプロジェクト単位で蓄積できる。

3-7. 実行モード（foreground / background）

Subagent には2つの実行モードがある。

foreground（既定）: 完了まで待機し、結果を即座に受け取る
background: 非同期で開始し、後から結果を追跡する

foreground は結果を待って次の判断に使いたい場合に向く。background は長時間かかるタスクや、複数ジョブの並列実行に向く。

以下のシーケンス図で2つのモードの違いを示す。

CLI でのエージェント実行例を示す。

# foreground でレビューを実行
claude --agent code-reviewer "このPRをレビューして"

# 最新の実行を再開（--continue）
claude --continue --resume-agent <agent-run-id>

# ファイル入出力を指定して実行
claude --agent code-reviewer --input plan.md --output report.md

--continue は最新の実行を再開する。特定の実行を再開したい場合は --resume-agent <id> で run-id を明示指定する。

3-8. 権限と安全性

Subagent の権限は permissionMode で制御する。

モード	説明
`default`	通常の権限確認フローに従う
`acceptEdits`	ファイル編集を自動承認する
`bypassPermissions`	すべての権限確認をスキップする
`plan`	計画のみ実行し、副作用を起こさない

Task ツール（サブエージェント起動）は plan を除くモードで利用できる。plan モードでは Task が無効化されるため、Subagent からさらに別のエージェントを起動する構成は取れない。

権限の細かい制御には /permissions を使う。Task(<agent-name>) 単位で許可・拒否を設定できる。たとえば Task(code-reviewer) を許可し、Task(deployer) を拒否するといった運用が可能である。

すべてのカスタム Subagent の起動を一括で禁止したい場合は、起動時に --disallowedTools "Task" を指定する。

3-9. Skills / Memory / Hooks 連携

Subagent は親のメイン会話から独立した実行環境で動く。そのため、連携設定を明示的に行う必要がある。

Skills の継承

Subagent は親の Skill を自動継承しない。レビュー用エージェントがコーディング規約 Skill を参照する必要がある場合、frontmatter の skills: で明示指定する。未指定のまま「知っている前提」で動かすと精度が落ちやすい。

Memory の範囲制御

memory.scope でエージェントの記憶範囲を制御する。チームで共有するエージェントには project を推奨する。none にすると毎回まっさらな状態で起動し、user にすると個人の全プロジェクトで記憶を共有する。

Hooks との連動

Subagent 固有の hooks を frontmatter に定義できる。メイン会話の Stop hook は、Subagent 実行時には SubagentStop として評価される。これにより、エージェント終了時に固有のバリデーションや通知を挟める。

3-10. 分離実行（isolation）

isolation で Subagent の実行環境を分離できる。誤操作や意図しない副作用を防ぐために、タスクに応じた分離レベルを選択する。

isolation	説明	用途例
`workspace-write`	既定。ワークスペースへの書き込みを許可	コード修正、ファイル生成
`read-only`	読み取り専用	調査、レビュー、ログ解析
`danger-full-access`	強い権限で実行	システム設定変更など

background: background と isolation: read-only を組み合わせると、長時間の読み取り専用ジョブを独立実行ワーカーとして動かせる。監視ログの継続解析などに有効である。

danger-full-access は名前の通り危険な設定である。ファイルシステムやネットワークへの広範なアクセスを許可するため、本当に必要な場合のみ使用する。

3-11. 再開・圧縮・履歴

Subagent の実行履歴は ~/.claude/agents/runs/ に保存される。各実行は run-id ごとの JSONL ファイルとして記録される。

長時間実行では自動 compact が動作する。compact はコンテキストが肥大化した際に要約を生成し、トークン消費を抑える仕組みである。自動 compact を無効化したい場合は環境変数を設定する。

export CLAUDE_CODE_AUTO_COMPACT_SUBAGENTS=false

履歴の保持期間は既定で30日間である。cleanupPeriodDays を設定すれば期間を変更できる。CI 環境など履歴が不要な場合は短縮し、監査目的なら延長するとよい。

3-12. ワークフローでの役割

Subagent はワークフローの中で複数の役割を担える。典型的な4パターンを示す。

高ボリューム隔離

テストログ、巨大な grep 結果、監視ログの解析など、出力量が多い作業を隔離する。メイン会話の文脈を汚さずに済む。

並列探索

認証・DB・API など独立した領域を同時に調査する。1つのメイン会話で逐次的に調べるよりも速く、各領域の専門エージェントに任せられる。

直列チェーン

reviewer → optimizer → fixer のように、複数のエージェントを順番に実行する。前段の出力を次段の入力として渡すパイプライン構成である。

自律運用

background Subagent と hooks を組み合わせて継続監視を実現する。ファイル変更の検知やテスト結果の定期チェックなど、人手を介さない運用に適している。

3-13. 設計上の注意

Subagent を導入する際は、以下の制約と落とし穴に留意していただきたい。

ネスト不可: Subagent は Subagent をネスト起動できない。2段階の委任が必要な場合はメイン会話で直列チェーンを組む。
反復対話には不向き: 何度もやり取りしながら詰める作業なら、メイン会話の方が速い。Subagent は「投げて待つ」使い方が基本である。
返却要約の肥大化: Subagent が返す要約が冗長だと、メイン会話の文脈を再び圧迫する。本文指示で「要点のみ返す」と明記するとよい。
最小権限の維持: bypassPermissions を常用しない。必要なツールだけを tools で列挙し、権限は最小限に保つ。
Skills の明示指定: skills 未指定で「知っている前提」にすると精度が落ちやすい。参照すべき Skill は必ず frontmatter に書く。

関連記事

4. Hooks ── イベント駆動の自動化エンジン

4-1. 役割

HooksはClaude Codeライフサイクルの各地点で自動実行されるイベント駆動オートメーションである。
CLAUDE.mdやSkillsはLLMが「読んで守る」仕組みだが、Hooksはそれとは異なるアプローチを取る。
イベントが発火した瞬間にシェルコマンドやHTTPリクエストが実行される。
LLMの判断に依存しない決定論的制御を実現できる点が、Hooksの最大の価値である。

「必ず実行されなければ困る処理」をHooksに置くのが基本方針である。
逆に、LLMの裁量に任せてよい処理はCLAUDE.mdやSkillsに記述する。
この切り分けが運用設計の出発点となる。

4-2. Hookライフサイクル（17イベント）

Claude Codeは17のイベントポイントを公開している。
セッション開始から終了まで、主要な操作の前後にフックを差し込める。

全17イベントの一覧を以下に示す。

#	イベント名	発火タイミング
1	SessionStart	セッション開始・再開・クリア・コンパクト時
2	UserPromptSubmit	ユーザーがプロンプトを送信した直後
3	PreToolUse	ツール実行の直前
4	PermissionRequest	許可確認が表示される直前
5	PostToolUse	ツール実行の成功直後
6	PostToolUseFailure	ツール実行の失敗直後
7	Notification	通知が送られるタイミング
8	SubagentStart	サブエージェント起動時
9	SubagentStop	サブエージェント停止時
10	Stop	メインエージェント停止時
11	TeammateIdle	チームメイトがアイドル状態になった時
12	TaskCompleted	タスク完了時
13	ConfigChange	設定変更の検出時
14	WorktreeCreate	ワークツリー作成時
15	WorktreeRemove	ワークツリー削除時
16	PreCompact	コンパクト実行の直前
17	SessionEnd	セッション終了時

以下のmermaid図でライフサイクルの流れを俯瞰する。

セッション開始から終了まで、ツール実行のたびにPre/Postが対で発火する。
サブエージェントにもStart/Stopがあり、入れ子構造を制御できる。
補助イベント群は特定条件で独立して発火する。

4-3. どこに定義するか（スコープ）

Hooksの定義場所は6つある。
スコープの広い順に並べる。

定義場所	スコープ	用途
Managed policy settings	組織全体	企業ポリシーの強制適用
`~/.claude/settings.json`	ユーザー全体	個人の共通フック
`.claude/settings.json`	プロジェクト共有	チーム共通のフック
`.claude/settings.local.json`	ローカル個人	個人用の上書き
Plugin: `hooks/hooks.json`	プラグイン単位	プラグイン同梱のフック
Skill/Subagent frontmatter	実行中のみ	スキル有効期間限定のフック

Skill/Subagent frontmatterに書いたHooksは、そのスキルやサブエージェントが有効な間だけ動く。
セッション全体に効かせたい処理には向かない。

/hooksメニューはcommand hookの追加・削除・一覧確認に強い。
HTTP hookはsettings JSONを直接編集する必要がある。

4-4. matcherの正しい使い方

matcherはイベントの発火条件を絞り込む正規表現である。
指定を誤ると意図しないタイミングでフックが走る。

matcherの基本ルールを整理する。

""、"*"、未指定はすべて「常に一致」として扱われる
ツール系イベント（PreToolUse, PostToolUse等）はtool_nameに対してマッチする
SessionStartは起動理由（startup|resume|clear|compact）に対してマッチする
SessionEndは終了理由（clear, logout, prompt_input_exit等）に対してマッチする

一方、matcherを受け付けないイベントもある。
以下は常時発火するため、matcherを書いても無視される。

UserPromptSubmit
Stop
TeammateIdle
TaskCompleted
WorktreeCreate
WorktreeRemove

たとえばStopイベントにmatcherを書いても意味がない。
後述の最小構成サンプルでもStopにはmatcherを付けていない。

4-5. ハンドラー種別と実行特性

Hooksのハンドラーは4タイプある。
それぞれ実行方法と得意領域が異なる。

タイプ	実行方法	主な用途
`"command"`	シェルコマンド実行	スクリプト・lint・通知
`"http"`	JSON POSTを送信	外部API連携・Webhook
`"prompt"`	単発LLM判定	軽い条件判定
`"agent"`	ツール使用可の検証エージェント	ファイル検証を伴う判定

command型が最も汎用性が高く、実運用の中心になる。
http型は外部サービスとの連携に使う。
prompt型とagent型はLLMに判定を委ねる特殊なタイプである。

実行時の共通特性も押さえておく。

matcherに一致した複数hookは並列実行される
同一ハンドラーは自動的にdedupeされる
デフォルトtimeoutはcommand 600秒、prompt 30秒、agent 60秒

4-6. Hook入出力の基本

すべてのhookは共通の入力データを受け取る。
command hookはstdin経由、HTTP hookはリクエストbody経由で以下が渡される。

session_id ── セッション識別子
transcript_path ── 会話ログのパス
cwd ── 現在の作業ディレクトリ
permission_mode ── 現在の権限モード
hook_event_name ── 発火したイベント名

command hookの制御はexit codeで行う。

exit code	意味
0	成功。処理を続行する
2	ブロック系エラー。対応イベントでは処理を中断する
その他	非ブロッキングエラー。警告を出すが処理は続行する

exit 0とexit 2の使い分けが最重要である。
exit 2はブロック対応イベントでのみ効果を発揮する。

4-7. イベント別「ブロック可能/不可」

exit 2でブロックできるかどうかはイベントごとに決まっている。
この区分を間違えると、止めたい処理が素通りする。

ブロック可能なイベント

PreToolUse
PermissionRequest
UserPromptSubmit
Stop
SubagentStop
TeammateIdle
TaskCompleted
ConfigChange（ただしpolicy_settings由来はブロック不可）
WorktreeCreate（非0で失敗扱い）

ブロック不可のイベント

PostToolUse
PostToolUseFailure
Notification
SubagentStart
PreCompact
SessionEnd
WorktreeRemove

PostToolUseやNotificationはブロックできない。
これらのイベントではログ記録や通知送信など、副作用のない処理を実行する。

4-8. JSON decisionの使い分け

exit codeだけでなく、JSON出力で細かい制御ができる。
ただしイベントごとにdecision形式が異なる点に注意する。

Top-level decisionを使うイベント

UserPromptSubmit、PostToolUse、PostToolUseFailure、Stop、SubagentStop、ConfigChangeはstdoutに"decision": "block"を出力してブロックする。

PreToolUseの推奨形式

{
  "hookSpecificOutput": {
    "permissionDecision": "deny"
  }
}

permissionDecisionはallow、deny、askの3値を取る。
top-level decisionによるブロックも動作するが、これは旧方式である。
現行はhookSpecificOutput方式を使う。

PermissionRequestの形式

{
  "hookSpecificOutput": {
    "decision": {
      "behavior": "allow"
    }
  }
}

behaviorはallowまたはdenyを指定する。

TeammateIdle / TaskCompleted

これらはJSON decisionではなくexit code主体で制御する。
exit 2でブロック、exit 0で続行という単純な仕組みである。

PreToolUseでtop-level decisionを使うコードが古い記事に残っている場合がある。
新規実装ではhookSpecificOutput.permissionDecisionを使用していただきたい。

4-9. HTTP hooksの注意点

HTTP hookはcommand hookと同じJSON構造をPOST bodyとして送信する。
外部サービスとの連携に便利だが、制御の仕組みが異なる。

押さえるべきポイントを4つ挙げる。

レスポンスが2xx + JSON bodyの場合、そのJSON bodyがdecisionとして処理される
非2xxレスポンスは非ブロッキングエラーとして扱われ、処理は進む
接続失敗やtimeoutも同様に非ブロッキングエラーになる
ステータスコード単体ではブロックできない

つまり、HTTP hookで処理をブロックしたければ「2xxを返しつつJSON bodyにdecisionを含める」必要がある。
403や500を返してもブロックにはならない。
この仕様はfail-open設計であり、外部サービス障害時にClaude Codeが止まらないようにしている。

4-10. Prompt/Agent hooksの実運用

prompt hookとagent hookはLLMに判定を委ねるハンドラーである。
command hookでは書きにくい柔軟な条件判定に向く。

対応イベントは以下の8つである。

PermissionRequest
PostToolUse
PostToolUseFailure
PreToolUse
Stop
SubagentStop
TaskCompleted
UserPromptSubmit

LLMの応答スキーマは統一されている。

{ "ok": true }

{ "ok": false, "reason": "テストが不足している" }

ok: falseはexit 2と同様にブロック扱いになる。
reasonフィールドでブロック理由をClaude Codeに伝達できる。

使い分けの目安はシンプルである。
テキスト情報だけで判定できる軽い条件にはprompt hookを使う。
ファイル内容の読み取りやコマンド実行が必要ならagent hookを使う。

4-11. 非同期hooks（async）

通常のhookはイベント発火時に同期実行され、完了を待つ。
長時間かかる処理ではこの待ち時間がボトルネックになる。

非同期hookを使えばバックグラウンドで実行できる。

対象はtype: "command"のみ
async: trueを指定する
実行結果を待たずに処理が進む

ただし制約がある。
非同期hookはブロックもdecision制御もできない。
systemMessageやadditionalContextを返した場合、次のターンで反映される。

非同期hookは通知送信やログ書き出しなど、結果を待つ必要がない処理に向く。

4-12. 最小構成サンプル

実運用で頻出する3パターンを1つのsettings.jsonにまとめた最小構成を示す。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm -s lint --fix"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "作業が完了していれば {\"ok\": true}、未完了なら {\"ok\": false, \"reason\": \"不足点\"} を返す。入力: $ARGUMENTS"
          }
        ]
      }
    ]
  }
}

この構成は3つの役割を果たす。

PreToolUse + Bash matcher: 危険なシェルコマンドの実行を事前にブロックする
PostToolUse + Edit|Write matcher: ファイル編集後に自動でlint修正を走らせる
Stop + prompt hook: タスク完了時にLLMが作業漏れを判定する

Stopはmatcher非対応イベントなので、matcherは省略している。
matcherを書いても無視されるため、省略するのが正しい書き方である。

4-13. /hooksと運用管理の要点

/hooksコマンドはHookの運用管理インターフェースである。
主要な操作をまとめる。

hookの追加・削除・一覧確認ができる
一時停止はdisableAllHooks: trueを設定する（/hooksのトグルでも可）
managed policy由来のhooksはmanaged側で無効化しない限り止められない

設定ファイルの反映タイミングには注意が必要である。
Claude Codeはセッション開始時に設定ファイルのスナップショットを取る。
セッション中にJSONファイルを直接編集しても即時反映されない。
変更後は/hooksでレビュー・反映操作を行う必要がある。

settings.jsonを直接編集した場合、反映にはセッション再起動か/hooksでのレビューが必要である。
編集したのに動かないときは、まずこの仕様を確認していただきたい。

4-14. 実践ユースケース

効果が高い順に7つのユースケースを紹介する。

1. 破壊操作ブロック（PreToolUse + Bash matcher）

rm -rfやgit push --forceなどの破壊コマンドをexit 2でブロックする。
CLAUDE.mdに「禁止」と書くだけではLLMが見落とす可能性がある。
Hooksなら確実に止められる。

2. 保護ファイル編集ブロック（PreToolUse + Edit|Write matcher）

.envやロックファイルなど、触ってほしくないファイルへの書き込みをブロックする。
tool_inputからファイルパスを読み取り、対象なら exit 2 を返す。

3. 保存後整形（PostToolUse + Edit|Write matcher）

ファイル編集のたびにlintやformatterを自動実行する。
pnpm lint --fixやblackなど、プロジェクトの整形ツールを指定する。

4. 完了判定の強化（Stop / SubagentStop）

promptまたはagent hookでタスク完了条件を検証する。
テスト未実行や型エラー放置のまま終了することを防げる。

5. 通知連携（Notification）

長時間タスクの完了をSlackやDiscordに通知する。
async hookと組み合わせると通知処理の完了を待たずに進める。

6. 監査ログ（ConfigChange / SessionEnd）

設定変更やセッション終了を外部ログサービスに記録する。
チーム開発での操作追跡に有用である。

7. 非同期検証（PostToolUse + async: true）

ファイル編集後にバックグラウンドでテストやビルドを走らせる。
結果は次ターンのコンテキストに反映される。

4-15. 運用設計の指針

Hooksを安定運用するための設計原則を5つ挙げる。

Block系はfail-closed寄りに設計する。
判定に迷ったらブロックする方向に倒す。
安全側に倒しておけば、誤ブロックはユーザーが手動で解除できる。

フックは冪等にする。
同じhookが複数回実行されても結果が変わらないように書く。
並列実行やリトライで二重実行される可能性がある。

長時間処理にはtimeoutを明示する。
デフォルトのcommand 600秒は多くの処理に十分だが、外部API呼び出しなどは短めに設定する。

Stop/SubagentStopの無限ループを防ぐ。
Stopでok: falseを返すとClaudeが再試行し、再びStopが発火する。
入力JSONのstop_hook_activeフラグを参照してループを検出する。

JSONを返すhookはstdout汚染を避ける。
hookがJSON decisionを返す場合、stdoutに余計な文字列を混ぜない。
デバッグ出力はstderrに書く。

4-16. Hooksと他機能の役割分担

Claude Codeの5機能はそれぞれ得意領域が異なる。
Hooksの守備範囲を明確にするため、役割分担を整理する。

用途	推奨機能
ルール記述	CLAUDE.md
手順化	Skills
隔離実行	Subagents
外部連携	MCP
強制自動化	Hooks

Hooksは「実行保証」が必要な箇所に限定するのが最も効果的である。
すべてをHooksで自動化しようとすると、設定が肥大化して保守が困難になる。
LLMの判断で十分な処理はCLAUDE.mdやSkillsに任せる。
Hooksは「LLMが守らなかったときに困る処理」だけを受け持つ。

Hooksをさらに深掘りしたい場合は以下を参照されたい。

5. MCP Servers ── 外部システムとの接続プロトコル

5-1. 役割

MCP（Model Context Protocol）は Claude Code と外部システムを接続する標準プロトコルである。GitHub・Jira・Sentry・データベース・Slack など、多様なサービスを「ツール」として Claude Code に認識させることができる。

従来はツールごとに個別のインテグレーションが必要だった。MCP はこれを統一的なプロトコルで解決する。外部サービスを MCP サーバーとして実装すれば、Claude Code は自然言語の文脈でそのサービスを呼び出せる。

5-2. 接続方式（推奨順）

MCP サーバーとの通信には 3 つの方式がある。選定の優先順位は以下の通りである。

1. HTTP（Streamable HTTP）

リモート連携の標準方式である。Claude Code がHTTPエンドポイントへリクエストを送り、レスポンスを受け取る。クラウド上のMCPサーバーと接続する際はこの方式を第一候補にする。

2. stdio

ローカル実行向けの方式である。Claude Code がサブプロセスとして MCP サーバーを起動し、標準入出力で通信する。ローカルファイル操作やローカル DB への接続に適している。

3. SSE（Server-Sent Events）

非推奨（deprecated）である。既存の SSE ベースサーバーとの互換性維持のみに使う。新規導入では HTTP を選択する。

SSE は将来的に廃止される予定である。既存システムであっても、移行計画を立てておくことを推奨する。

5-3. 追加・管理コマンド

MCP サーバーの追加から確認・削除まで、CLI で操作できる。

コマンド	用途
`claude mcp add`	サーバーを追加する
`claude mcp add-json`	JSON 形式で追加する
`claude mcp list`	登録済みサーバー一覧を表示する
`claude mcp get <name>`	特定サーバーの詳細を確認する
`claude mcp remove <name>`	サーバーを削除する
`claude mcp add-from-claude-desktop`	Claude Desktop の設定を取り込む

Claude Code のセッション内では /mcp コマンドで接続中サーバーの一覧と状態を確認できる。認証エラーや接続切れの検知にも使える。

5-4. インストール設計（3 方式）

方式 1: リモート HTTP サーバー（第一選択）

クラウド上の MCP サーバーに接続する場合に使う。

claude mcp add my-server https://my-server.example.com/mcp

方式 2: ローカル stdio サーバー

ローカルマシン上でサーバーを起動して接続する場合に使う。

claude mcp add my-local-server -- npx -y @example/mcp-server --port 3000

-- 以降がサーバー実行コマンドとして解釈される。この区切りが重要で、オプションの配置順序を間違えると意図しない動作になる。

--transport・--env・--scope・--header などのオプションは、サーバー名よりも前に配置する。-- 以降に置くとサーバー起動コマンドの引数として解釈されてしまう。

# 正しい順序
claude mcp add --scope user --env API_KEY=xxx my-server -- npx my-mcp

# 間違った順序（--scope がサーバー引数になる）
claude mcp add my-server -- npx my-mcp --scope user

方式 3: リモート SSE サーバー（既存互換のみ）

SSE 方式のサーバーが既にある場合のみ使用する。

claude mcp add --transport sse my-sse-server https://legacy.example.com/sse

5-5. scope と保存先

MCP サーバーの登録には 4 つの scope がある。用途に応じて使い分ける。

scope	説明	保存先
`local`（既定）	現在のプロジェクトでのみ利用	`~/.claude.json`
`project`	チーム全員で共有	プロジェクトルートの `.mcp.json`
`user`	全プロジェクト共通の個人設定	`~/.claude.json`
`managed`	組織が管理	`managed-mcp.json`

# project scope で追加（チーム共有）
claude mcp add --scope project github-server https://github-mcp.example.com

# user scope で追加（個人の全プロジェクト共通）
claude mcp add --scope user my-personal-server -- npx my-tool

旧名称との対応に注意が必要である。local は旧ドキュメントで project と呼ばれていた。user は旧 global に相当する。ドキュメントやブログ記事を参照する際は読み替えていただきたい。

project scope のサーバーは初回利用時に承認ダイアログが表示される。チームメンバーが初めてそのプロジェクトを開いた際に、明示的な許可が求められる仕組みである。承認状態をリセットするには次のコマンドを実行する。

claude mcp reset-project-choices

scope の優先順位

同名のサーバーが複数の scope に存在する場合、より局所的な設定が優先される。

5-6. 優先順位と競合解決

同名サーバーが複数 scope に登録されている場合の解決ルールは単純である。local > project > user の順に優先される。

たとえば github という名前のサーバーが user scope と local scope の両方にある場合、local 側の設定が使われる。特定プロジェクトだけ別の GitHub MCP サーバーを使いたい場合は、local scope で上書き登録すればよい。

5-7. .mcp.json の実践ポイント

チームで共有する MCP サーバー設定は .mcp.json を Git 管理する。ファイルはプロジェクトルートに配置し、mcpServers オブジェクトにサーバー定義を記述する。

{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://github-mcp.example.com/mcp"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/pg-mcp", "--connection", "${DB_URL}"],
      "env": {
        "DB_PASSWORD": "${DB_PASSWORD:-default_dev_pw}"
      }
    }
  }
}

環境変数の展開をサポートしている。展開対象は command・args・env・url・headers の各フィールドである。

${VAR}: 環境変数 VAR の値に展開する
${VAR:-default}: VAR が未定義の場合にデフォルト値を使う

デフォルト値を指定していない ${VAR} が未定義のままだと、設定のパースに失敗する。CI 環境やチームメンバーの環境差異に備えて、デフォルト値の設定を検討していただきたい。

5-8. 認証（OAuth 含む）

HTTP サーバーでは /mcp コマンドから OAuth 認証フローを開始できる。認証が必要なサーバーに初回接続すると、ブラウザが起動して認証を完了する流れになる。

動的クライアント登録に対応していないサーバーでは、事前にクライアント情報を登録する必要がある。次のオプションで設定する。

claude mcp add \
  --client-id "my-app-id" \
  --client-secret "my-app-secret" \
  --callback-port 8080 \
  my-oauth-server https://oauth-server.example.com/mcp

--client-secret に指定した値は macOS ではキーチェーンに、その他の OS では資格情報ファイルに安全に保存される。平文で設定ファイルに残ることはない。

5-9. Dynamic updates と可観測性

MCP サーバーは list_changed 通知に対応している。サーバー側でツール・プロンプト・リソースの構成が変わると、Claude Code は再接続なしで自動的に最新の定義を取得する。

大規模運用では /mcp コマンドを定期的に確認する運用が有効である。認証トークンの期限切れやサーバー停止を早期に検知できる。特に長時間セッションでは、途中で認証が切れるケースが起こりやすい。

5-10. MCP resources / prompts の使い分け

MCP サーバーはツール以外に resources と prompts も提供できる。

resources

外部データをコンテキストに取り込む機能である。@ 記法でプロンプト内から参照する。

@server:protocol://resource/path

複数の resource を 1 つのプロンプトで同時に参照できる。データベースのスキーマ情報と API 仕様書を同時に読み込ませる、といった使い方が可能である。

prompts

MCP サーバー側で定義されたプロンプトテンプレートを実行する機能である。

/mcp__servername__promptname arg1 arg2

引数はスペース区切りで渡す。サーバー側で定義されたパラメータに順番にマッピングされる。定型的な問い合わせやレポート生成に活用できる。

5-11. Tool Search（大規模 MCP 向け）

MCP サーバーが提供するツール数が多くなると、全ツール定義がコンテキストを圧迫する。Tool Search を有効にすると、必要なツールだけをオンデマンドで読み込める。

環境変数 ENABLE_TOOL_SEARCH で制御する。

設定値	動作
`auto`（既定）	全ツール数の 10% を閾値として自動判定する
`auto:<N>`	閾値を N 個に変更する（例: `auto:5`）
`true`	常に Tool Search を有効化する
`false`	Tool Search を無効化する

# 閾値を5に設定
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全無効化
ENABLE_TOOL_SEARCH=false claude

McpSearch ツールの権限を deny に設定すると、明示的に Tool Search を抑止できる。ツール数が少ない環境では不要なオーバーヘッドを避けられる。

5-12. 出力上限と性能チューニング

MCP サーバーからの出力が大きすぎるとコンテキストを消費し、応答品質が下がる。Claude Code にはトークンベースの制限がある。

パラメータ	値	用途
警告閾値	10,000 tokens	超過でコンソールに警告を表示する
既定最大値	25,000 tokens	これを超えた出力は切り捨てられる
`MAX_MCP_OUTPUT_TOKENS`	任意の数値	最大値を変更する
`MCP_TIMEOUT`	ミリ秒	サーバー起動タイムアウトを変更する

# 出力上限を50,000トークンに拡大
MAX_MCP_OUTPUT_TOKENS=50000 claude

# タイムアウトを60秒に設定
MCP_TIMEOUT=60000 claude

ログ収集サーバーやデータ分析サーバーでは、出力が 25,000 トークンを超えることが珍しくない。上限を引き上げるか、サーバー側でページング処理を実装して対処する。

5-13. Plugin / Claude.ai 連携

Plugin 連携

Claude Code の Plugin は MCP サーバーを同梱できる。Plugin を有効化すると、含まれる MCP サーバーが自動的に起動する。Plugin 開発者が独自のツールを配布する手段として活用されている。

Claude.ai 連携

Claude.ai 側で追加済みのコネクタ（MCP サーバー）は Claude Code にも反映できる。Web UI で設定したサーバーをそのまま CLI 環境で利用可能になる。

いずれの場合も、/mcp コマンドの一覧で接続元を識別できる。Plugin 由来・Claude.ai 由来・手動追加のサーバーが区別して表示される。

5-14. 組織統制（Managed MCP）

組織で MCP サーバーの利用を統制するには 2 つの方式がある。

方式 1: managed-mcp.json（排他的制御）

管理者が定義したサーバーのみを使用可能にする方式である。ユーザーが独自にサーバーを追加することはできない。

配置パスは OS ごとに異なる。

OS	パス
macOS	`/Library/Application Support/ClaudeCode/managed-mcp.json`
Linux / WSL	`/etc/claude-code/managed-mcp.json`
Windows	`C:\Program Files\ClaudeCode\managed-mcp.json`

{
  "mcpServers": {
    "approved-github": {
      "type": "url",
      "url": "https://corp-github-mcp.internal/mcp"
    }
  }
}

方式 2: allowedMcpServers / deniedMcpServers（ポリシー制御）

ユーザーによるサーバー追加を許可しつつ、利用範囲を制限する方式である。柔軟性とガバナンスを両立できる。

5-15. allowlist / denylist の厳密ルール

ポリシー制御のエントリには、次のいずれか 1 つだけを指定する。複数の条件を 1 エントリに混在させることはできない。

serverName: サーバー名で一致判定する（* ワイルドカード可）
serverCommand: stdio サーバーの起動コマンドで判定する（* 可）
serverUrl: リモートサーバーの URL で判定する（* 可）

{
  "allowedMcpServers": [
    { "serverName": "github-*" },
    { "serverUrl": "https://*.corp.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted-*" }
  ]
}

動作には厳密なルールがある。以下を正確に把握しておく必要がある。

denylist は常に最優先で評価される。allowlist に含まれていても deny されていれば拒否される
allowlist に serverCommand が 1 件でもあると、stdio サーバーはコマンドが一致しなければ拒否される
allowlist に serverUrl が 1 件でもあると、リモートサーバーは URL が一致しなければ拒否される
"allowedMcpServers": []（空配列）は完全ロックダウンとして機能する。全サーバーの追加が拒否される

allowlist に serverCommand を 1 件追加するだけで、他の全 stdio サーバーがブロック対象になる。意図せずチームの作業を止めてしまう事故が起きやすい。導入前にテスト環境で挙動を確認しておくことを推奨する。

5-16. セキュリティ観点

MCP は強力な機能だが、信頼境界の管理が不可欠である。以下の点に留意していただきたい。

サードパーティ製 MCP サーバーは、提供元の信頼性を必ず確認する。コードレビューが理想である
外部コンテンツを取得する MCP（Web スクレイピング、メール取得など）は prompt injection のリスクが高い。取得データに悪意ある指示が含まれる可能性がある
project scope で .mcp.json を共有する際は、資格情報を直書きしない。環境変数展開（${VAR}）を使う
組織導入では managed-mcp.json か allowedMcpServers / deniedMcpServers で最小許可の原則を適用する

5-17. 実運用ユースケース

MCP を活用した代表的なワークフローを 5 パターン紹介する。

パターン 1: 障害対応

Sentry MCP で最新エラーを取得し、GitHub MCP で該当コミットと PR を特定する。原因を解析したら、そのまま修正 PR を作成する。エラー検知から修正提出までを 1 セッションで完結できる。

パターン 2: データ分析

PostgreSQL MCP でクエリを実行し、集計結果を取得する。Claude Code がデータを整形してレポートを生成する。SQL の組み立てから可視化までを自然言語で指示できる。

パターン 3: 開発運用

GitHub MCP で Issue の確認・PR の作成・レビューコメントの取得を自動化する。日次の PR 棚卸しやラベル整理をワンコマンドで実行できる。

パターン 4: 仕様実装

Jira MCP でチケットの要件を取得し、Figma MCP でデザインを確認する。Slack MCP で関連議論を参照しながら、要件に基づいた実装を進める。情報収集と実装を行き来する必要がなくなる。

パターン 5: 顧客対応

CRM の MCP で顧客情報を引き出し、対応履歴を確認する。メール下書きの作成まで含めた横断的なワークフローを Claude Code 上で完結させる。

MCP サーバーの自作方法について、以下の記事で詳しく解説している。

Claude Codeの能力を自作MCPサーバーで拡張する

6. 実践アーキテクチャ ── 5機能をどう組み合わせるか

ここまで CLAUDE.md・Skills・Subagents・Hooks・MCP の5機能を個別に解説してきた。
本章では、プロジェクトの規模や体制に応じた組み合わせパターンを示す。

6-1. 個人開発向け（軽量構成）

個人開発では「最小限のルールで素早く回す」ことを優先する。
設定に時間をかけすぎず、必要になったら拡張する方針が適している。

各機能の使い方は以下の通りである。

機能	方針
CLAUDE.md	言語・フレームワーク・コーディング規約など最小限のルールのみ記述する
Skills	`/review`・`/commit`・`/release-note` など日常的に使う手順をSkill化する
Hooks	format（PostToolUse）と危険コマンド抑止（PreToolUse）の2種に絞る
MCP	GitHub Server を project scope で追加する。issue tracker があればそれも接続する
Subagents	通常は使わない。大規模なコード探索や横断調査が必要な場合にのみ起動する

構成の全体像を以下に示す。

個人開発でも Hooks の format 自動実行は導入コストに対して効果が大きい。prettier や black などの既存フォーマッタを PostToolUse で呼ぶだけで、手動修正の手間が消える。

6-2. チーム開発向け（標準構成）

チーム開発では「全員が同じ基準で動く」ことが重要になる。
CLAUDE.md だけでなく .claude/rules/ を使い、言語やディレクトリごとに規約を分割する。
Hooks には品質ゲートと監査ログを追加し、属人化を防ぐ。

各機能の使い方は以下の通りである。

機能	方針
CLAUDE.md	チーム共通の開発規約・アーキテクチャ方針を記述する
.claude/rules/	言語別（TypeScript/Python等）・ディレクトリ別（frontend/backend等）の規約を分離する
Skills	PRレビュー・デプロイ手順・障害対応 runbook などチーム共通の手順を Skill 化する
Hooks	品質ゲート（lint/test）+ 監査ログ出力 + Slack 通知を組み合わせる
MCP	project scope で共通化し、全メンバーが同じ外部接続を使えるようにする
Subagents	レビュー系・検証系のタスクを分離し、メインエージェントの応答性を維持する

構成の全体像を以下に示す。

.claude/rules/ のファイルには globs フィールドを設定できる。たとえば globs: "src/frontend/**" と書けば、フロントエンドのコードを編集するときだけそのルールが読み込まれる。不要なコンテキスト消費を抑えつつ、領域特化のルールを適用できる。

6-3. エンタープライズ向け（統制構成）

組織規模が大きくなると「誰が何をできるか」を統制する必要がある。
Claude Code は Managed 設定によって組織管理者が一元的に制御できる仕組みを持つ。

機能	方針
Managed CLAUDE.md	組織ポリシーを全プロジェクトに強制適用する
Managed settings	`allowManagedHooksOnly` で未承認フックの実行を禁止する
Managed MCP	承認済みサーバーのみ接続可能にし、allow/deny で制御する
Hooks	運用チームが標準フックセットを配布する。個人追加は制限する
Skills	運用チームが標準 Skill を配布する。障害対応・デプロイ手順を統一する
Plugins	機能セットを Plugin として固めてバージョン管理・配布する

構成の全体像を以下に示す。

allowManagedHooksOnly を有効にすると、Managed 設定以外で定義されたフックは一切実行されなくなる。導入前に既存のローカルフックを棚卸しし、必要なものは Managed 側へ移行しておく必要がある。

6-4. 意思決定フローチャート

「この機能はどこに置くべきか」と迷ったとき、以下のフローチャートで判断できる。

フローチャートの補足を以下にまとめる。

CLAUDE.md vs .claude/rules/ の使い分け

CLAUDE.md に書くルールが増えてきたら .claude/rules/ への分割を検討する。目安として、CLAUDE.md が 200 行を超えたら分割のタイミングである。globs 指定で読み込み対象を限定すれば、トークン消費も最適化できる。

Skills vs CLAUDE.md の使い分け

常に参照する必要がない情報は Skills に移す。たとえば「デプロイ手順」を CLAUDE.md に書くと、デプロイと無関係な作業中もトークンを消費する。/deploy Skill にすれば、必要なときだけ読み込まれる。

Hooks のタイプ選択

単純な条件分岐と固定アクションなら command hook で十分である。「このコード変更は安全か」のような判断が必要な場合は、prompt hook や agent hook を使う。command hook は LLM を経由しないため高速で決定論的に動作する。

7. 導入ロードマップ ── 段階的に拡張する

5つの機能を一度に導入する必要はない。
効果の高い順・リスクの低い順に段階的に導入するのが現実的である。
以下の6ステップで進めることを推奨する。

Step 1: `/init` で CLAUDE.md を作る

claude /init

すべての起点は CLAUDE.md である。/init コマンドを実行すると、プロジェクト構造を解析して初期 CLAUDE.md を自動生成する。まずはここに最小限のルール（言語・フレームワーク・コーディング規約）だけを書く。

なぜ最初なのか。CLAUDE.md がないと Claude Code はプロジェクトの文脈を持たない。他の機能を追加する前に、基盤となるコンテキストを整える必要がある。

Step 2: 繰り返し説明している手順を Skill 化する

「毎回同じ説明をしている」と感じたら、それは Skill 化のサインである。PRレビューの観点、コミットメッセージの規約、リリースノートの書き方など、繰り返し使う手順を .claude/skills/ に配置する。

なぜ2番目なのか。CLAUDE.md に手順を詰め込むとトークンが無駄になる。まず CLAUDE.md を運用してみて「これは毎回要らない」と気づいた情報から Skill に切り出す。実体験に基づいた分離が最も効果的である。

Step 3: 事故防止・品質保証を Hook 化する

PreToolUse と PostToolUse を優先的に導入する。たとえば「rm -rf の実行を阻止する」「ファイル保存後に自動フォーマットを実行する」といった決定論的な制御から始める。

なぜ3番目なのか。Step 1〜2 で Claude Code の動きを把握してから Hook を入れる方が、不要なフックを作らずに済む。「Claude がやりがちなミス」が見えてから対策するのが合理的である。

Step 4: 重い探索・検証を Subagent に逃がす

コードベースが大きくなり、1つのタスクに時間がかかるようになったら Subagent の出番である。レビュー・テスト検証・横断検索などを分離し、メインエージェントの応答速度を維持する。

なぜ4番目なのか。Subagent は「処理が重い」という実感がなければ導入動機が生まれない。Step 1〜3 で日常運用を確立してから、ボトルネックに対して投入する方が効果を実感しやすい。

Step 5: 外部依存が出たら MCP を project scope で追加する

GitHub・Jira・Sentry・Slack など外部サービスとの連携が必要になったタイミングで MCP を追加する。project scope で設定すれば、チーム全員が同じ接続設定を共有できる。

なぜ5番目なのか。外部連携は認証・ネットワーク・権限管理など考慮事項が多い。まずローカル完結の機能（Step 1〜4）を安定させてから、外部接続を追加する方がトラブルシュートしやすい。

Step 6: 肥大化したルールは .claude/rules/ に分解する

運用が進むと CLAUDE.md が長くなり、Skills の数も増えてくる。このタイミングで .claude/rules/ にルールを分割し、globs でスコープを限定する。

なぜ最後なのか。分割は「何が肥大化したか」を知らないとできない。Step 1〜5 を経て実際に肥大化を体験してから分割する方が、適切な粒度で分けられる。先に分割構造を設計しても、実態と乖離することが多い。

この順番は「まず動かし、次に繰り返しを減らし、そして制御を加え、最後に構造化する」というサイクルに沿っている。完璧な設計を先に作ろうとするより、運用しながら改善する方が結果的に速い。

8. Plugin化 ── 拡張を持続可能にする

8-1. なぜ Plugin 化するのか

ここまで解説した5つの機能は単体でも動作する。
しかし運用規模が大きくなると、以下の問題が浮上する。

依存関係が暗黙化する。 Skill が特定の Hook や MCP の存在を前提としていても、それが明示されていない。環境を再構築すると動かなくなる。
機能セットの境界が曖昧になる。 .claude/skills/ と .claude/agents/ と settings の hooks が散在し、どこからどこまでが「一つの機能」なのか把握しにくくなる。
バージョンが分散して再現性が落ちる。 メンバーごとに設定ファイルのバージョンが異なり、「自分の環境では動く」状態が発生する。
チーム配布と統制が難しくなる。 新メンバーのオンボーディング時に「この Skill を入れて、この Hook を設定して、この MCP を追加して」と手順が増え続ける。

Plugin 化の目的は「配布」そのものではない。構造化・境界定義・再利用・統治・再現性を実現するためのアーキテクチャ手段である。

8-2. Plugin が束ねる対象

Plugin は以下の構成要素を1つのパッケージに束ねる。

構成要素	役割
CLAUDE.md / rules	方針と常時ルール。Plugin 専用の CLAUDE.md やルールファイルを含められる
skills/	手順と知識のオンデマンド化。Skill は Plugin の名前空間で管理される
agents/	分離実行ワーカー。Subagent 定義を Plugin 内に同梱できる
hooks/hooks.json	イベント駆動の強制自動化。Plugin 専用のフック定義を持てる
.mcp.json	外部連携の接続設定。必要な MCP サーバー設定を同梱する
settings.json	既定挙動の設定。Plugin 固有の設定値を管理する

1〜5章で解説した機能が、すべて Plugin の中に収まる構造になっている。

8-3. 最小プラグイン構成

Plugin のディレクトリ構造は以下の通りである。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json
└── settings.json

plugin.json は Plugin のメタデータを定義する。最小限の構成は以下の通りである。

{
  "name": "my-plugin",
  "description": "Team standard extension bundle",
  "version": "1.0.0"
}

構成上のポイントを以下にまとめる。

plugin.json は .claude-plugin/ ディレクトリの配下に配置する。Plugin ルート直下ではない点に注意していただきたい。
skills/・agents/・hooks/ は Plugin ルート直下に置く。.claude/ プレフィックスは不要である。
Skill は /plugin-name:skill-name という名前空間でアクセスする。たとえば上の例では /my-plugin:review となる。

Plugin 内の Skill 名は自動的に名前空間化される。これにより、複数の Plugin が同名の Skill を持っていても衝突しない。

8-4. 既存構成からの移行手順

すでに .claude/skills/ や .claude/agents/、settings 内の hooks で運用している場合、以下の手順で Plugin へ移行できる。

Step 1: 棚卸し

現在の構成要素を一覧化する。.claude/skills/ 内の Skill、.claude/agents/ 内の Subagent 定義、settings.json 内の hooks 設定、.mcp.json の接続先を洗い出す。

Step 2: Plugin ディレクトリに再配置

Plugin ルートを作成し、各要素を移動する。hooks は .claude/settings.json 内の定義から hooks/hooks.json へ切り出す。ファイルパスの参照先が変わる場合は、スクリプトのパスも修正する。

Step 3: ローカル検証

claude --plugin-dir ./my-plugin

このコマンドでローカルの Plugin ディレクトリを直接読み込める。Skills が名前空間付きで認識されるか、Hooks が正しく発火するか、MCP 接続が動作するかを確認する。

Step 4: 配布

検証が完了したら、project scope またはマーケットプレイスで配布する。Git リポジトリとしてバージョン管理し、SemVer でタグを付与する。

8-5. 運用設計

Plugin のライフサイクルは以下のように設計する。

開発フェーズ: standalone で高速反復する

新しい Skill や Hook を試すときは、.claude/ 配下で直接開発する。Plugin 化のオーバーヘッドなしに素早く検証できる。

安定化フェーズ: Plugin 化してバージョン固定する

動作が安定したら Plugin ディレクトリに移し、plugin.json でバージョンを付与する。これにより「どのバージョンの機能セットを使っているか」が明確になる。

チーム展開: project scope で標準化する

Plugin を project scope で導入し、チーム全員が同じ機能セットを使えるようにする。新メンバーは Plugin をインストールするだけで環境が整う。

組織統制: Managed で管理する

組織全体に適用する Plugin は Managed 設定で配布する。管理者が承認した Plugin のみ利用可能にすることで、セキュリティと統制を確保する。

運用上の注意点を以下にまとめる。

CHANGELOG と SemVer で変更を管理する。破壊的変更はメジャーバージョンを上げる。
Plugin が依存するファイル（スクリプト、設定ファイル等）は Plugin ルート内に閉じる。外部パスへの依存は移植性を損なう。
Plugin 間の依存は避ける。各 Plugin は独立して動作する設計にする。

Plugin 内のフックスクリプトが Plugin 外のファイルを参照していると、別環境で動作しない。相対パスは Plugin ルートからの相対パスとして解決されるため、スクリプトの配置場所に注意していただきたい。

8-6. 結論

Plugin は「拡張機能の追加手段」ではない。Claude Code の拡張を長期運用可能にするためのアーキテクチャ単位である。

CLAUDE.md・Skills・Subagents・Hooks・MCP の5機能は、最終的に Plugin へ収束させると最も再利用しやすくなる。個人開発では standalone で十分だが、チーム導入や組織展開を見据えるなら、早い段階で Plugin 化の構造を意識しておくことを推奨する。

9. 参考リンク集

公式ドキュメント

ドキュメント	URL
Extend Claude Code（機能概要）	https://code.claude.com/docs/en/features-overview
Memory	https://code.claude.com/docs/en/memory
メモリ（日本語）	https://code.claude.com/docs/ja/memory
Skills	https://code.claude.com/docs/en/skills
スキル（日本語）	https://code.claude.com/docs/ja/skills
Subagents	https://code.claude.com/docs/en/sub-agents
サブエージェント（日本語）	https://code.claude.com/docs/ja/sub-agents
Hooks guide	https://code.claude.com/docs/en/hooks-guide
Hooks reference	https://code.claude.com/docs/en/hooks
フック（日本語）	https://code.claude.com/docs/ja/hooks
MCP	https://code.claude.com/docs/en/mcp
MCP（日本語）	https://code.claude.com/docs/ja/mcp
Plugins	https://code.claude.com/docs/en/plugins
プラグイン（日本語）	https://code.claude.com/docs/ja/plugins
Plugins reference	https://code.claude.com/docs/en/plugins-reference
Settings	https://code.claude.com/docs/en/settings

筆者の関連記事

Hooks・Subagents・MCP など各機能の深掘り記事を公開している。本ガイドと併せて参照していただきたい。

Hooks 関連

エージェント関連

実践・連携関連

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up