Claude Code 解説書 — Thread 4 of 8
拡張レイヤー概論
CLAUDE.md・メモリ・6つの拡張機能
スレッド2で見たエージェンティックループ（AIが「調査→実行→検証」を自律的に繰り返す動作サイクル）は、5カテゴリの組み込みツールだけでも多くのタスクをこなせる。 しかし実際のプロジェクトでは、「チーム固有のコーディング規約を毎回伝える」「外部のデータベースに接続する」「デプロイ手順を自動化する」といったニーズが出てくる。
これらを実現するのが拡張レイヤーだ。Claude Codeのコアループを変更せず、その「上」に機能を追加する仕組みである。 本スレッドでは、拡張レイヤーを構成するすべての要素の全体像を理解し、スレッド5〜8で各機能を深掘りするための前提知識を築く。
このスレッドの位置づけ：スレッド1〜3で「Claude Codeとは何か」「どう動くか」「どう使うか」を学んだ。ここからは「どう拡張するか」のフェーズに入る。本スレッドは全拡張機能の俯瞰であり、各機能の詳細はスレッド5（Skills）、6（MCP）、7（Subagents/Agent Teams）、8（Hooks/Plugins/自動化）に続く。
Section 4.1
4.1CLAUDE.md — プロジェクトの「指示書」
CLAUDE.mdとは、Claude Codeが毎セッション開始時に自動で読み込むマークダウンファイルだ。人間がプロジェクト固有の指示を書き、Claudeがそれを「コンテキスト」（判断材料）として利用する。新入社員にプロジェクトのルールブックを渡すのと同じ発想で、セッションが変わっても一貫した行動を引き出せる。
なぜ必要なのか
Claude Codeの各セッションはフレッシュなコンテキストウィンドウ（まっさらな記憶領域）で始まる。 前回のセッションで「うちはpnpmを使う」と伝えても、次回起動時にはその情報は消えている。 CLAUDE.mdはこの問題を解決する。ファイルに書いておけば、毎回自動的にClaudeの判断材料に含まれるのだ。
配置場所と読み込み順序
CLAUDE.mdは3つのスコープ（適用範囲）に配置でき、より具体的（ローカル）な指示が優先される。
| スコープ | 配置場所 | 用途 | 共有範囲 |
|---|---|---|---|
| マネージドポリシー | /Library/.../ClaudeCode/CLAUDE.md | 組織全体のルール | 全ユーザー |
| プロジェクト | ./CLAUDE.md or ./.claude/CLAUDE.md | チーム共有のプロジェクトルール | チームメンバー（Git経由） |
| ユーザー | ~/.claude/CLAUDE.md | 個人の好み | 自分のみ（全プロジェクト） |
図4-1：CLAUDE.mdの3階層とその優先順位。マネージドポリシーは除外不可。
Claude Codeはカレントディレクトリからルートに向かって上に走査し、途中のすべてのCLAUDE.mdを読み込む。 たとえば foo/bar/ で起動すると、foo/bar/CLAUDE.md と foo/CLAUDE.md の両方が読み込まれる。 サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリ内のファイルにアクセスした時点でオンデマンドに読み込まれる。
書き方のベストプラクティス
CLAUDE.mdは「コンテキストとして」読み込まれるものであり、技術的な強制力はない。 そのため、書き方の質が遵守率を左右する。公式ドキュメントが推奨するポイントは以下の通りだ。
| 観点 | 推奨 | 理由 |
|---|---|---|
| 分量 | 200行以下 | 長いほどコンテキストを圧迫し、遵守率が低下する |
| 構造 | マークダウン見出し＋箇条書き | Claudeが構造をスキャンして素早く理解する |
| 具体性 | 検証可能な指示 | 「コードを整理して」→ × 「2スペースインデントを使う」→ ○ |
| 一貫性 | 矛盾する指示を排除 | 矛盾があるとClaudeが任意に片方を選ぶ |
具体例：プロジェクトCLAUDE.mdの典型的な内容
# Build & Test - パッケージマネージャ: pnpm を使用（npm禁止） - テスト実行: pnpm test（コミット前に必ず実行） - 単体テスト1件: pnpm test -- --testPathPattern="path" # Code Style - TypeScript strict mode - インデント: 2スペース - 命名規則: camelCase（変数・関数）、PascalCase（型・クラス） # Architecture - APIハンドラ: src/api/handlers/ - 共有ユーティリティ: src/shared/utils/
外部ファイルのインポート
CLAUDE.mdが肥大化しそうな場合、@path/to/file 構文で外部ファイルを参照できる。 インポートされたファイルはセッション開始時に展開され、CLAUDE.mdと同時にコンテキストに読み込まれる。たとえば、READMEやパッケージ情報を取り込む場合は以下のように書く。
具体例：@importによる外部ファイル参照
プロジェクト概要は @README.md を参照。 利用可能なnpmコマンドは @package.json を確認。 # 個人設定（Gitにコミットしない） - @~/.claude/my-project-instructions.md
初回のみ承認ダイアログが表示される：プロジェクトで初めて外部インポートが検出されると、読み込むファイルの一覧が表示され承認を求められる。拒否した場合、そのインポートは無効のままになる。
Section 4.2
4.2オートメモリ（MEMORY.md）
CLAUDE.mdが「人間が書く指示書」だとすれば、オートメモリは「Claude自身が書くメモ帳」だ。 セッション中にClaudeが発見したビルドコマンド、デバッグのパターン、ユーザーの好みなどを自動的に記録し、次回以降のセッションで活用する。
| 観点 | CLAUDE.md | オートメモリ |
|---|---|---|
| 誰が書くか | 人間（開発者） | Claude自身 |
| 内容 | 指示・ルール | 学習した知見・パターン |
| スコープ | プロジェクト/ユーザー/組織 | ワーキングツリーごと |
| 読み込み | 全内容を毎セッション | MEMORY.mdの先頭200行を毎セッション |
| 適した用途 | コーディング規約、ビルドコマンド | デバッグ知見、操作の好み |
保存場所とファイル構造
オートメモリはプロジェクトごとに ~/.claude/projects/<project>/memory/ に保存される。<project> はGitリポジトリから自動導出されるため、同一リポジトリ内のworktreeやサブディレクトリはメモリを共有する。
~/.claude/projects/<project>/memory/ ├── MEMORY.md # インデックス（毎セッション先頭200行読み込み） ├── debugging.md # デバッグパターンの詳細メモ ├── api-conventions.md # API設計の知見 └── ... # Claudeが必要に応じて作成
MEMORY.md はインデックスとして機能し、先頭200行のみがセッション開始時に自動読み込みされる。 200行を超える詳細は別ファイル（debugging.md 等）に分離され、Claudeが必要なときにオンデマンドで読みに行く。
仕組みと管理
オートメモリはデフォルトで有効だ。セッション中に「Writing memory」「Recalled memory」というメッセージが表示されたら、Claudeがメモリの書き込み・読み出しを行っている。
管理は /memory コマンドで行う。このコマンドからメモリの閲覧、編集、有効/無効の切り替えが可能だ。 プログラム的に無効化するには、設定ファイルで "autoMemoryEnabled": false とするか、環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を設定する。
マシンローカルである点に注意：オートメモリはマシン間で共有されない。クラウド環境やCI/CDで実行する場合、学習済みの知見は利用できない。チーム全員に共有したい知見はCLAUDE.mdに書き出すべきだ。
Section 4.3
4.3.claude/rules/ — ルールの整理
プロジェクトが大きくなると、CLAUDE.mdが肥大化する。.claude/rules/ ディレクトリは、指示をトピック別のファイルに分割して管理する仕組みだ。
your-project/ ├── .claude/ │ ├── CLAUDE.md # メインの指示書 │ └── rules/ │ ├── code-style.md # コードスタイルの規約 │ ├── testing.md # テストの規約 │ └── security.md # セキュリティ要件
パス固有ルール
ルールファイルの先頭にYAML frontmatter（メタデータ記述用の構文）で paths フィールドを指定すると、特定のファイルパスに一致するファイルをClaudeが操作するときだけルールが適用される。これにより、不要なルールがコンテキストを消費するのを防げる。
具体例：TypeScript APIファイル専用のルール
--- paths: - "src/api/**/*.ts" --- # API Development Rules - 全APIエンドポイントに入力バリデーションを含めること - 標準エラーレスポンス形式を使用すること - OpenAPIドキュメントコメントを記述すること
CLAUDE.md vs Rules vs Skills — 使い分け早見表
| 観点 | CLAUDE.md | .claude/rules/ | Skill |
|---|---|---|---|
| 読み込み | 毎セッション（全量） | 毎セッション or パス一致時 | オンデマンド |
| スコープ | プロジェクト全体 | ファイルパスに限定可 | タスク固有 |
| 適した用途 | ビルドコマンド、コア規約 | 言語別・ディレクトリ別ガイドライン | 参照資料、呼び出し型ワークフロー |
整理の原則は明快だ。「毎回必要な核心情報」はCLAUDE.md、「特定条件で必要な規約」はrules、「必要なときだけ呼び出す知識やワークフロー」はSkillに置く。
Section 4.4
4.4拡張レイヤーの全体マップ
Claude Codeの拡張は、大きく6つの機能＋1つのパッケージング層で構成される。 それぞれがエージェンティックループの異なる位置に接続し、異なる問題を解決する。
図4-2：拡張レイヤー全体マップ。6つの機能がエージェンティックループの異なる位置に接続する。破線枠のAgent Teamsは実験的機能。
各機能の役割を一言で整理すると以下の通りだ。
| 機能 | 何をするか | いつ使うか | 具体例 |
|---|---|---|---|
| CLAUDE.md | 毎セッション読み込まれる永続コンテキスト | 「常に○○せよ」というルールの定義 | 「pnpmを使え」「テストしてからコミットせよ」 |
| Skills | Claudeが使える知識・ワークフロー | 再利用可能な手順・参照資料 | /deploy でデプロイ手順を実行 |
| MCP | 外部サービスに接続するプロトコル | 外部データや操作が必要なとき | DBクエリ、Slack投稿、ブラウザ操作 |
| Subagents | 隔離コンテキストで実行し要約を返すワーカー | コンテキスト分離・並列タスク | 大量ファイルを読んでキー知見だけ報告 |
| Agent Teams | 複数の独立セッションを協調 | 並列研究、チーム開発、仮説検証 | セキュリティ・パフォーマンス・テストの同時レビュー |
| Hooks | 特定イベント時に自動実行される決定的スクリプト | LLM不要の予測可能な自動化 | ファイル編集後にESLintを自動実行 |
Pluginsはこれらの上位に位置するパッケージング層で、Skills・Hooks・Subagents・MCPサーバーを1つのインストール可能なユニットにバンドルする。 プラグイン内のスキルは名前空間（namespace、衝突を避けるための接頭辞）で区別される。 たとえば /my-plugin:review のように「プラグイン名:スキル名」でアクセスする。
Section 4.5
4.5機能の選び方 — 比較ガイド
6つの機能は一見似ているものがある。ここでは公式ドキュメントの比較をベースに、「どちらを選ぶべきか」の判断基準を整理する。
Skill vs Subagent
どちらも「メインセッションの外にある機能」だが、解決する問題が異なる。
| 観点 | Skill | Subagent |
|---|---|---|
| 本質 | 再利用可能な指示・知識・ワークフロー | 隔離されたコンテキストを持つワーカー |
| 最大の利点 | コンテキスト間でコンテンツを共有 | 作業が分離され、要約だけが親に返る |
| 適した用途 | 参照資料、呼び出し型ワークフロー | 多数のファイルを読む調査、並列作業 |
| 組み合わせ | Subagentは起動時にSkillをプリロードできる。Skillは context: fork でSubagentとして実行可能。 | |
判断の具体例
「チームのAPIスタイルガイドをClaudeに教えたい」→ Skill（参照資料として、必要なときに読み込む）
「100ファイルのセキュリティ監査を走らせたい」→ Subagent（大量読み取りを分離し、メインのコンテキストを汚さない）
Subagent vs Agent Team
どちらも作業を並列化するが、アーキテクチャが根本的に異なる。
| 観点 | Subagent | Agent Team |
|---|---|---|
| コンテキスト | 独自ウィンドウ → 結果を親に返す | 独自ウィンドウ → 完全に独立 |
| 通信 | メインエージェントにのみ報告 | チームメイト同士が直接メッセージ |
| 協調 | メインが全作業を管理 | 共有タスクリストで自己協調 |
| トークンコスト | 低い（要約のみ親に返る） | 高い（各メンバーが独立インスタンス） |
移行の判断基準：並列Subagentを使っているがコンテキスト制限に当たる、またはSubagent同士がコミュニケーションする必要がある場合、Agent Teamsが自然な次のステップとなる。ただしAgent Teamsは現在実験的機能であり、デフォルトでは無効だ。
MCP vs Skill
MCPは「接続手段」、Skillは「活用知識」であり、そもそも解決する問題が異なる。
| 観点 | MCP | Skill |
|---|---|---|
| 本質 | 外部サービス接続のプロトコル | 知識・ワークフロー・参照資料 |
| 提供するもの | ツールとデータアクセス | 知識と手順 |
| 具体例 | Slack連携、DBクエリ、ブラウザ操作 | コードレビュー手順、デプロイワークフロー |
たとえば、MCPサーバーがデータベースへの接続を提供し、Skillがそのデータベースのスキーマ、よく使うクエリパターン、各テーブルの用途を教える——という組み合わせが典型的だ。
意思決定フローチャート
「自分のニーズにはどの機能が最適か？」を判断するためのフローチャートを示す。
図4-3：意思決定フローチャート — 「何を拡張したいか」から最適な機能を選択する
Section 4.6
4.6コンテキストコストの理解
拡張機能を追加するたびに、Claude Codeのコンテキストウィンドウ（AIが一度に「読める」情報量の上限）が消費される。 過度に詰め込むとウィンドウが埋まるだけでなく、情報のノイズが増えてClaudeの判断精度が低下する。 各機能が「いつ」「何を」「どれだけ」コンテキストに読み込むかを理解することが、効果的な設計の鍵だ。
| 機能 | 読み込みタイミング | 読み込まれるもの | コンテキストコスト |
|---|---|---|---|
| CLAUDE.md | セッション開始時 | 全内容 | 毎リクエストに含まれる |
| Skills | 開始時 + 使用時 | 開始時：説明文のみ / 使用時：全内容 | 低（説明文のみが毎回）* |
| MCP | セッション開始時 | 全ツール定義とJSONスキーマ | 毎リクエストに含まれる |
| Subagents | スポーン（生成）時 | 新規コンテキスト（指定Skill含む） | メインセッションから分離 |
| Hooks | トリガー発火時 | なし（外部スクリプトとして実行） | ゼロ（出力を返さない限り） |
* Skillの disable-model-invocation: true を設定すると、手動呼び出し（/名前）するまでClaudeからは完全に不可視になり、コンテキストコストがゼロになる。副作用のあるスキル（デプロイ等）にはこの設定が推奨される。
図4-4：機能別のコンテキスト読み込みタイミングとコスト。CLAUDE.mdとMCPは「常時」、Skillsは「段階的」、SubagentsとHooksは「メインに影響なし」。
コンテキスト設計の鉄則：「常時読み込み」の層（CLAUDE.md + MCPツール定義）はできるだけスリムに保つ。 参照頻度の低い情報はSkillに移してオンデマンド化し、大量の読み取りが必要な調査作業はSubagentに委任する。 MCPサーバーは使わないものを切断しておく（/mcp コマンドでサーバーごとのトークンコストを確認可能）。
Section 4.7
4.7機能の組み合わせパターン
各拡張機能は単独でも機能するが、組み合わせることで真価を発揮する。公式ドキュメントで紹介されている代表的なパターンを整理する。
| パターン | 仕組み | 具体例 |
|---|---|---|
| Skill + MCP | MCPが接続手段を提供し、Skillがその効果的な使い方を教える | MCPでDBに接続 + Skillにスキーマとクエリパターンを記述 |
| Skill + Subagent | Skillがサブエージェントを起動して並列作業を実行 | /audit スキルがセキュリティ・パフォーマンス・スタイルのSubagentを同時起動 |
| CLAUDE.md + Skills | CLAUDE.mdに常時ルール、Skillにオンデマンド参照資料 | CLAUDE.md:「API規約に従え」+ Skill: 完全なAPIスタイルガイド |
| Hook + MCP | HookがイベントトリガーでMCP経由の外部アクションを実行 | 重要ファイル変更時にSlackに自動通知 |
図4-5：4つの代表的な機能組み合わせパターン
レイヤリングの原則
機能を複数レベル（ユーザー全体、プロジェクト、プラグイン、マネージドポリシー）で定義した場合、以下のルールで合成される。
| 機能 | 合成ルール |
|---|---|
| CLAUDE.md | 加算的 — 全レベルの内容がすべてコンテキストに加わる。矛盾時はClaudeが判断し、より具体的な指示を優先する傾向がある |
| Skills / Subagents | 名前で上書き — 同名の定義が複数レベルにある場合、優先順位（managed > user > project）に従い1つが採用される |
| MCP | 名前で上書き — local > project > user の順 |
| Hooks | マージ — すべてのソースから登録されたHookが、一致するイベントに対して全て発火する |
✦まとめ — スレッド5以降へのロードマップ
本スレッドで、Claude Codeの拡張レイヤーを構成する全要素の俯瞰が完了した。核心ポイントを振り返る。
CLAUDE.mdはプロジェクトの「指示書」として毎セッション自動読み込みされ、200行以下に保つのが鉄則。 肥大化したら.claude/rules/でトピック分割し、パス固有ルールでコンテキストを節約する。オートメモリはClaude自身が知見を蓄積する仕組みで、MEMORY.mdの先頭200行が毎セッション読み込まれる。
6つの拡張機能は、それぞれ異なる問題を解決し、エージェンティックループの異なる位置に接続する。 選択の軸は「常時コンテキスト vs オンデマンド」「内部知識 vs 外部接続」「ループ内 vs ループ外」の3つだ。 そしてコンテキストコストを常に意識し、「常時読み込み層はスリムに、重い処理は分離する」のが設計の原則である。
図4-6：応用フェーズのロードマップ。スレッド5〜8は任意の順序で学習可能。
homula's Expertise
homulaの支援体制
Claude Codeの拡張レイヤー設計は、プロジェクト規模と組織要件によって最適解が異なります。homulaは400社超の支援実績をもとに、CLAUDE.md設計・Skills構築・MCP接続基盤・CI/CD自動化まで一気通貫で支援します。
ブートキャンプ（3-5日）
Claude Codeの導入設計・CLAUDE.md作成・Skills/MCPのプロトタイプ構築を5日間で完了。チームへの展開計画まで含む。
導入パッケージ（2-4ヶ月）
拡張レイヤーの設計から本番運用まで。CLAUDE.md標準化、カスタムSkills開発、MCPサーバー構築、CI/CDパイプライン統合。
よくある質問
公式ドキュメントでは200行以下が推奨されています。CLAUDE.mdの全内容は毎リクエストのコンテキストに含まれるため、長いほどトークンを消費し、Claudeの判断精度も低下します。頻繁に参照しない規約は.claude/rules/でトピック分割し、さらに大きな参照資料はSkillに移すのがベストプラクティスです。
CLAUDE.mdは人間が書く「指示書」で、プロジェクトのルールや規約を定義します。オートメモリはClaude自身が書く「メモ帳」で、セッション中に発見したビルドパターンやデバッグの知見を自動記録します。CLAUDE.mdはGitでチーム共有でき、オートメモリはマシンローカルです。
MCPは「外部サービスへの接続手段」（データベースクエリ、Slack投稿等）、Skillは「知識・ワークフロー・参照資料」（コードレビュー手順、APIスタイルガイド等）です。典型的にはMCPがDBへの接続を提供し、SkillがそのDBのスキーマとクエリパターンを教える——という組み合わせで使います。
Subagentsはメインエージェントが管理する「ワーカー」で、隔離されたコンテキストで作業し要約だけを親に返します。Agent Teamsは複数の独立したClaude Codeセッションが共有タスクリストで自己協調する仕組みです。Subagent同士のコミュニケーションが必要になったらAgent Teamsへの移行を検討してください。ただしAgent Teamsは現在実験的機能です。
Hooksは特定イベント（ファイル編集後等）で発火する決定的スクリプトであり、Claude Codeのエージェンティックループの「外側」で実行されます。LLMを経由しないため、コンテキストウィンドウを一切消費しません。ただし、Hookの出力をClaudeに返すよう設定した場合はその分のコストが発生します。