最初にポイントをざっくり書く
CLAUDE .md、Rules、Skills、Subagents、MCPs 。5 つのレイヤーの使い分けの感覚はこれだけ覚えればいい
- どういう思想で働いてほしいかは CLAUDE .md
- この領域では絶対に守る知識は Rules
- 人（自動もあり）が開始する作業手順は Skills
- 自動で任せたい重い作業は Subagents
- 外部世界と触るなら MCP
Claude Code は「全部ルールを書くほど賢くなる」わけではない
レイヤーを間違えると、むしろ指示を無視し始める
X で 毎日 AI 情報を配信してるコムテです。Agentic AI / AI 駆動開発 / Claude Code などを中心に情報を配信しています
この記事は Mario Ottmann 氏の Claude Code Customization Guide にインスピレーションを受け、Anthropic 公式ドキュメントと論文も引っ張り出して検証したもの
よくある失敗
あるある過ぎて…
- CLAUDE .md に全部詰め込む
- ワークフロー指示を Rules に書く
- レイヤーの役割を理解せず混ぜる
ポイント
段階的に構築すること
- まず CLAUDE .md で地図を作る
- 次に Rules で専門知識を固める
- 繰り返し作業は Skills に切り出す
- 重くなったら Subagents に任せる
- 外部と繋ぐ必要が出たら MCPs を使う
- トリガー発動は、スラッシュコマンド
わからなくなったら
- CLAUDE .md はプロジェクトの地図
- Rules は専門知識
- Skills は繰り返し作業
- Subagents は複雑な自動化
- MCPs は外部ツール連携
コムテは？
ワイ？これで SaaS を１週間くらいで作るよ
- スラッシュコマンドを多用
- CLAUDE .md は簡潔に 200 行以内
- ドメイン知識は Rules
- MCP は、少なめに
- Skills は、多くても２つくらい
- Subagents は必須でない。必要なプロジェクトで
それじゃあ、解説始めるよー
Claude Code のカスタマイズ、CLAUDE .md だけで頑張ってない?
Claude Code を使い始めると、まず CLAUDE .md にあれこれ書き込みたくなるよね
プロジェクトのルール、コーディング規約、よく使うコマンド、全部ここに書いておけば Claude が賢くなるはずやと
やけど、ここで多くの開発者がハマる罠がある。CLAUDE .md に全部詰め込むと、むしろ Claude は指示を無視し始めるんよね
300 行を超えたあたりから、書いたはずのルールを平気でスルーするようになる
これは Claude Code のアーキテクチャを理解していないと起こる問題で、実は Claude Code には 5 つのカスタマイズレイヤーがあって、それぞれに明確な役割がある
このレイヤーを正しく使い分けることで、Claude は「何度言っても覚えない AI」から「プロジェクトを深く理解した相棒」に変わる
arxiv で公開されている研究 A Systematic Survey of Prompt Engineering in Large Language Models でも指摘されているけど、プロンプトエンジニアリングにおいて重要なのは「適切な粒度での指示の分離」なんよ。一つの巨大なプロンプトより、役割ごとに分離された複数の指示の方が、LLM はより正確に従う傾向がある
5 つのレイヤーの全体像
まず、Claude Code のカスタマイズは「内部レイヤー」と「外部レイヤー」に分かれる
内部レイヤーは Claude の「脳」を構成する 4 つの要素で、Claude がどう考え、何を知っていて、どう働くかを決める
| レイヤー | トリガー | 用途 |
|---|---|---|
| CLAUDE .md | 常に読み込み | プロジェクトの地図、基本設定 |
| Rules | パスベースまたは常に | ドメイン固有の深い知識 |
| Skills | ユーザーが起動 | 繰り返しワークフロー |
| Subagents | Claude が自動起動 | 複雑な自動タスク |
外部レイヤーは MCPs で、Claude の「手」として外部ツールに接続する役割を持つ
| レイヤー | トリガー | 用途 |
|---|---|---|
| MCPs | ツール利用時 | 外部ツールへのアクセス |
この構造を理解すると、使い分けの感覚は実はめっちゃシンプルになる
使い分けの感覚はこれだけ覚えればいい
迷ったときは、この 5 つの問いを順番に考えてみて
- どういう思想で働いてほしいかは CLAUDE .md
- この領域では絶対に守る知識は Rules
- 人が開始する作業手順は Skills
- 自動で任せたい重い作業は Subagents
- 外部世界と触るなら MCPs
arxiv の研究 RePrompt: Planning by Automatic Prompt Engineering for Large Language Models Agents では、LLM エージェントの性能は「適切なレイヤーでの指示の配置」に大きく依存することが示されている。中間フィードバックを活用した段階的な最適化が、タスク完了率を大幅に向上させるんよね
CLAUDE .md とは何か
CLAUDE .md は Claude Code の「マスター設定」で、セッションが始まるたびに必ず読み込まれる。公式ドキュメントでは「Memory」とも呼ばれていて、プロジェクト全体に適用される前提知識を置く場所や
配置できる場所は 4 つあって、優先度順に並べるとこうなる
| 種類 | 場所 | 共有範囲 |
|---|---|---|
| Enterprise | システムディレクトリ | 組織全体 |
| Project | ./CLAUDE .md | チーム全員 |
| User | ~/.claude/CLAUDE .md | 自分のみ |
| Local | ./CLAUDE.local.md | 自分のみ |
Project レベルの CLAUDE .md はリポジトリにコミットして、チームで共有する。User レベルは個人の好みを全プロジェクトに適用する。Local は git にコミットしたくない個人設定を置く場所や
CLAUDE .md に書くべきもの
CLAUDE .md はプロジェクトの「地図」であり「従業員ハンドブック」のようなもの。新入社員が初日に読む資料をイメージすると分かりやすい
具体的には
- フレームワーク規約（Next.js 14 App Router を使う、など）
- コード品質基準（DRY 原則、テストの書き方）
- アクセシビリティ要件
- CI/CD の期待値
- 利用可能な Skills、Rules、Subagents のインデックス
公式ドキュメントによると、CLAUDE .md は 300 行以下が目安。これを超えると Claude がすべてを正確に把握できなくなる傾向がある
CLAUDE .md に書かないべきもの
逆に、CLAUDE .md に書くべきでないものもある
- 深いドメイン知識（Rules に分離）
- ステップバイステップのワークフロー（Skills に分離）
- 特定ファイルパターンにのみ適用されるルール（Rules に分離）
よくある失敗は、CLAUDE .md に設計規約、セキュリティポリシー、データベースパターン、コーディングスタイル、全部を 1 ファイルに詰め込んでしまうこと。そうすると Claude はコンテキストの重要度を判断できなくなって、結果的に指示を無視し始める
CLAUDE .md の実践例
実際のプロジェクトで使われている CLAUDE .md の構造はこんな感じや
ポイントは「参照先へのリンク」として機能させること。詳細は Rules や Skills に任せて、CLAUDE .md は全体の地図に徹する
CLAUDE .md の import 機能
CLAUDE .md には他のファイルを import する機能がある。@path/to/file 構文を使う
相対パスと絶対パスの両方が使える。特に便利なのは、チームメンバーごとに個別の設定ファイルを読み込ませること
これは CLAUDE.local.md の代替として機能して、複数の git worktree で作業する場合に特に便利や
Rules とは何か
Rules は .claude/rules/ ディレクトリに配置する markdown ファイルで、ドメイン固有の深い知識を格納する場所や。CLAUDE .md との決定的な違いは「パスベースのフィルタリング」ができること
Rules のディレクトリ構造
.claude/rules/ 内のすべての .md ファイルは自動的にプロジェクトメモリとして読み込まれる
パスベースのフィルタリング
Rules の真価は「特定のファイルを編集しているときだけ読み込まれる」ことにある。YAML フロントマターで paths を指定する
この rule は、データベース関連のファイルを編集しているときだけ Claude のコンテキストに読み込まれる。CSS を編集しているときには読み込まれないから、コンテキストの無駄遣いを防げる
glob パターンの例
| パターン | マッチするもの |
|---|---|
**/*.ts | 任意ディレクトリの TypeScript ファイル |
src/**/* | src ディレクトリ以下のすべて |
*.md | プロジェクトルートの markdown |
src/**/*.{ts,tsx} | src 以下の .ts と .tsx |
Rules に書くべきもの
Rules は「専門部門のドキュメント」のようなもの。CLAUDE .md が全社共通のハンドブックなら、Rules は各部門の詳細マニュアルや
- フロントエンド
- セキュリティ要件（コード例付き）
- データベースパターン（RLS ポリシー、クエリ最適化）
- フレームワーク固有の詳細（Tailwind v4 のユーティリティマッピング）
Rules の実践例 - フロントエンド
Rules の実践例 - セキュリティ要件
このような rule があると、Claude は自動的に HTML をサニタイズし、埋め込み追加時に CSP ヘッダーを更新するようになる
CLAUDE .md と Rules の使い分け
| CLAUDE .md | Rules |
|---|---|
| 常に読み込まれる | パスフィルタ可能 |
| プロジェクト全体の基準 | ドメイン固有の深い知識 |
| クイックリファレンス形式 | 詳細なドキュメント |
| 単一ファイル | 複数のフォーカスしたファイル |
| 「ここでの働き方」 | 「X を具体的にどうやるか」 |
研究 Architecting Resilient LLM Agents では、行動を起こす前に完全なステップバイステップの計画を生成することで、推論の質とタスク完了率が向上することが示されている。これは Claude Code の Rules が提供する「コンテキストに応じた詳細な指示」の有効性を裏付けている
Skills とは何か
Skills はスラッシュコマンドとして展開される「繰り返し可能なワークフロー」を定義するもの。公式ドキュメントでは「Agent Skills」と呼ばれていて、Claude が特定のタスクを実行する方法を教える markdown ファイルや
重要なのは、Skills は「モデルが起動する」という点。ユーザーのリクエストが Skill の説明にマッチすると、Claude は自動的にその Skill を適用する
Skills のディレクトリ構造
Skills は 2 つの場所に配置できる
| 場所 | スコープ |
|---|---|
~/.claude/skills/ | 個人用、全プロジェクトで利用可能 |
.claude/skills/ | プロジェクト用、チームで共有 |
各 Skill はディレクトリで、その中に SKILL.md と追加のサポートファイルを含む
SKILL .md の構造
SKILL .md は YAML メタデータと Markdown 指示で構成される
description フィールドが特に重要で、Claude はこれを見て「いつこの Skill を使うべきか」を判断する
利用可能なメタデータフィールド
| フィールド | 必須 | 説明 |
|---|---|---|
| name | はい | スキル名（小文字、ハイフン、最大 64 文字） |
| description | はい | 用途と使用タイミング（最大 1024 文字） |
| allowed-tools | いいえ | 許可するツール |
| model | いいえ | 使用するモデル |
| context | いいえ | fork でサブエージェントコンテキストで実行 |
| hooks | いいえ | ライフサイクルフック |
| user-invocable | いいえ | スラッシュコマンドメニューに表示するか |
Skills に書くべきもの
Skills は「ユーザーの起動が必要で、実行中にユーザー入力が必要になる可能性があるマルチステップワークフロー」に最適
- アーキテクチャ決定（ユーザー確認が必要）
- コンテンツ生成ワークフロー
- 法的/コンプライアンスページ生成
- デプロイチェックリスト
- コードレビューワークフロー
Skills の実践例 - バックエンドアーキテクチャ
/backend-architecture と入力すると、Claude はこの決定ツリーに沿って一緒に考えてくれる
Skills と Rules の違い
Skills と Rules は似ているように見えるけど、根本的に異なる
| Skills | Rules |
|---|---|
| ユーザーがトリガー | パスベースで自動読み込み |
| ワークフロー指向 | 知識/コンテキスト指向 |
~/.claude/skills/ | .claude/rules/ |
| マルチステップの手順 | ドメイン固有のルール |
「Supabase を使うときのルール」は Rules に書く。「どの DB 技術を使うか決める手順」は Skills に書く
Subagents とは何か
Subagents は「専門的な AI アシスタント」で、複雑なマルチステップタスクを自律的に処理する。各 Subagent は独自のコンテキストウィンドウ、カスタムシステムプロンプト、特定のツールアクセス、独立した権限を持つ
Skills との決定的な違いは、Subagents は「Claude が自動的に起動する」こと。タスクが Subagent の説明にマッチすると、Claude はそこに委譲する
ビルトイン Subagents
Claude Code には 3 つのビルトイン Subagent がある
| Subagent | モデル | 用途 |
|---|---|---|
| Explore | Haiku（高速） | 読み取り専用のコードベース検索・分析 |
| Plan | Sonnet | 実装計画のためのリサーチ |
| general-purpose | 会話のモデルを継承 | 探索と変更の両方が必要な複雑タスク |
カスタム Subagents
本当の力はカスタム Subagent を定義することで発揮される。設定で定義しておくと、タスクが説明にマッチしたときに自動的に起動する
これを設定しておくと、「ログイン機能を実装した」と言ったあとに Claude が自動的にセキュリティ監査を実行する
Subagents のディレクトリ構造
| 場所 | スコープ |
|---|---|
~/.claude/agents/ | 個人用、全プロジェクトで利用可能 |
.claude/agents/ | プロジェクト用、チームで共有 |
Subagents のフロントマター
| フィールド | 説明 |
|---|---|
| name | 一意の識別子 |
| description | いつ委譲するかの説明 |
| tools | 使用可能なツール |
| model | sonnet, opus, haiku, inherit |
| permissionMode | default, acceptEdits, dontAsk, bypassPermissions, plan |
| skills | 読み込む Skills |
| hooks | ライフサイクルフック |
Skills と Subagents の使い分け
| Skills | Subagents |
|---|---|
| 現在の会話に知識を追加 | 独立したコンテキストで実行 |
| ユーザーが起動 | Claude が自動起動 |
| ガイダンスと標準向け | 複雑な自律タスク向け |
「PR レビューのやり方」を教えるなら Skills。「大規模なセキュリティ監査を自動実行」なら Subagents
研究 Prompt Injection Defense Patterns for LLM Agents では、「plan-then-execute」パターンがプロンプトインジェクション攻撃を緩和することが示されている。Subagents はまさにこのパターンを実現していて、信頼できないデータを処理する前に計画を定義し、許可されたツール呼び出しのみを実行する
Subagents の実践例 - コードレビュアー
フォアグラウンドとバックグラウンド実行
Subagents はフォアグラウンド（ブロッキング）またはバックグラウンド（並行）で実行できる
フォアグラウンドは完了するまでメイン会話をブロックする。権限プロンプトや質問はユーザーに渡される
MCPs とは何か
MCPs (Model Context Protocol) は Claude Code を外部ツールやデータソースに接続するオープンソース標準。内部レイヤー 4 つが「Claude の脳」を構成するなら、MCPs は「Claude の手」として外部世界とインタラクトする
GitHub、Slack、データベースなど、コードベース外の何かに触る必要があるなら MCPs の出番や
MCPs でできること
MCPs を接続すると、Claude Code に
- イシュートラッカーから機能を実装: 「JIRA issue ENG-4521 の機能を追加して GitHub に PR を作成」
- モニタリングデータを分析: 「Sentry と Statsig で ENG-4521 機能の使用状況を確認」
- データベースをクエリ: 「PostgreSQL から ENG-4521 機能を使った 10 人のランダムユーザーのメールを取得」
- デザインを統合: 「Slack に投稿された新しい Figma デザインに基づいてメールテンプレートを更新」
- ワークフローを自動化: 「この 10 人のユーザーにフィードバックセッションへの招待メールのドラフトを Gmail で作成」
MCP サーバーの管理
MCP インストールスコープ
| スコープ | 場所 | 共有範囲 |
|---|---|---|
| local | ~/.claude.json（プロジェクトパス下） | 自分のみ（現在のプロジェクト） |
| project | .mcp.json | チーム（git コミット） |
| user | ~/.claude.json | 自分のみ（全プロジェクト） |
MCP の実践例 - Sentry でエラー監視
よくある失敗パターン
ここまで各レイヤーを見てきたけど、失敗パターンも押さえておこう
失敗 1: CLAUDE .md に全部詰め込む
CLAUDE .md はクイックリファレンスであって、500 行のドキュメントではない。深いドメイン知識は Rules に分離すべき
失敗 2: ワークフローを Rules に書く
Rules はコンテキストであって、指示ではない。「常に DOMPurify を使う」は rule。「リーガルページを生成するときは X、Y、Z をする」は skill や
失敗 3: パスベースフィルタリングを使わない
データベースルールを CSS 編集時に読み込むのはコンテキストの無駄。paths フロントマターで関連ファイル編集時のみ読み込む
失敗 4: 自律タスクに Skills を使う
実行中にユーザー入力が不要なタスクは、Subagent として Claude が自動起動すべき。Skills はユーザー起動が必要なワークフロー向け
失敗 5: 外部統合を bash コマンドでハックする
外部アクセスを bash コマンドでやろうとするのは脆弱。MCPs が適切なツールインターフェースを提供する
失敗 6: CLAUDE .md をスキップする
CLAUDE .md なしでは、毎セッション同じことを繰り返し説明することになる。「Next.js 14 App Router を使ってることを忘れないで...」
決定フレームワーク - どのレイヤーを使う?
迷ったときは、この質問を順番に聞いてみて
-
プロジェクト全体の基準またはクイックリファレンス?
→ CLAUDE .md（フレームワーク規約、コード品質基準、アクセシビリティ、skills/rules のインデックス） -
深いドメイン知識?
→ Rules（デザインシステム、セキュリティ、データベースパターン、RLS ポリシー） -
トリガーする繰り返しワークフロー?
→ Skills（アーキテクチャ決定、コンテンツ生成、リーガルページ、デプロイチェックリスト） -
複雑な自律タスク?
→ Subagents（セキュリティ監査、コードベース探索、大規模リファクタリング、コンテンツ変換） -
外部ツールアクセスが必要?
→ MCPs（GitHub、データベース、Slack、CI/CD パイプライン）
実践的な組み合わせ例
フロントエンド開発スタック
- CLAUDE .md: Next.js 規約、React パターン、アクセシビリティ基準
- Rules: design-system.md、tailwind-v4.md
- Skills: /landing-page-builder
- Subagents: Explore（ビルトイン）
- MCPs: 通常不要
バックエンド開発スタック
- CLAUDE .md: Next.js 規約、コード品質、テスト要件
- Rules: database-supabase.md（パスフィルタ）、security.md
- Skills: /backend-architecture
- Subagents: Plan（ビルトイン）、security-auditor（カスタム）
- MCPs: Postgres、GitHub
コンテンツ作成スタック
- CLAUDE .md: コード品質、アクセシビリティ（生成ページ向け）
- Rules: design-system.md（一貫したフォーマット向け）
- Skills: /legal-pages
- Subagents: linkedin-to-mdx-blog（カスタム）
- MCPs: 通常不要
段階的な構築アプローチ
5 つのレイヤーすべてを一度に使う必要はない。段階的に構築していくのがベストプラクティス
ステップ 1: CLAUDE .md で地図を作る
まずはフレームワーク規約、コード品質基準、追加予定のもののインデックスから始める。これが基盤になる
ステップ 2: Rules でドメイン知識を固める
.claude/rules/ にデザインシステムとセキュリティ要件を作成。特定コンテキストでのみ重要なルールにはパスフィルタリングを使う
ステップ 3: 繰り返し作業を Skills に切り出す
週に 2-3 回やるワークフローを特定して、~/.claude/skills/ に SKILL.md と追加サポートファイルを含むディレクトリを作成
ステップ 4: 重い作業は Subagents に任せる
作業していて「Claude が自動的に専門エージェントを使えたら便利なのに」と思ったら、カスタム Subagent を設定する
ステップ 5: 外部連携が必要になったら MCPs を追加
外部ツールアクセスが必要になったら、適切な MCP サーバーを設定する
まとめ
Claude Code のカスタマイズは 5 つのレイヤーで構成される
内部レイヤー（Claude の設定）
- CLAUDE .md - プロジェクト全体の基準とクイックリファレンスインデックスを持つマスター設定
- Rules - オプションのパスベースフィルタリングを持つ深いドメイン知識
- Skills - 繰り返しマルチステッププロセスのためのユーザートリガーワークフロー
- Subagents - 必要に応じて Claude が起動する複雑タスク用の自律スペシャリスト
外部レイヤー（外部への橋渡し）
- MCPs - GitHub、データベース、Slack などの外部ツールへの接続
目標は 5 つのレイヤーすべてをどこでも使うことではない。適切な仕事に適切なレイヤーを使うことや
研究 Agent Security Bench（ICLR 2025）でも指摘されているように、効果的なシステムプロンプトを書くには専門知識が必要で、それをレイヤー構造で整理することがセキュリティと効率性の両方に寄与する
この使い分けができたとき、Claude Code は本当の力を発揮する
参考リンク
- Claude Code 公式ドキュメント - Settings
- Claude Code 公式ドキュメント - Skills
- Claude Code 公式ドキュメント - Subagents
- Claude Code 公式ドキュメント - MCP
- Claude Code 公式ドキュメント - Memory
- 元記事: Claude Code Customization Guide
- arxiv: A Systematic Survey of Prompt Engineering in LLMs
- arxiv: RePrompt: Automatic Prompt Engineering for LLM Agents
- arxiv: Architecting Resilient LLM Agents
- arxiv: Prompt Injection Defense Patterns
- arxiv: Agent Security Bench (ICLR 2025)
