Claude Code CLAUDE.md 設計のベストプラクティス——6レイヤーの使い分けと落とし穴

Claude Codeの設定ファイル、何が何だかわからなくなっていませんか。

CLAUDE.md、Rules、Commands、Skills、Agents、MCP、Plugins。公式ドキュメントを読んでも「で、結局どこに何を書けばいいの？」がはっきりしない。自分も最初はCLAUDE.mdにルールもワークフローも全部詰め込んで、コンテキストが溢れて前半の指示を忘れられる、という事故を繰り返していました。

2025年5月にClaude Codeへ導入された Skills 2.0 は、従来のカスタムスラッシュコマンドの大幅な拡張です。スキルを独立したコンテキストで実行する context: fork、使えるツールを制限する allowed-tools、モデルを指定する model といった設定が追加され、「AIへの指示をどう構造化するか」という設計の幅が広がりました。

この記事では、Skills 2.0を含む設定レイヤーの使い分けパターンと、運用で踏んだ落とし穴を共有します。

6つのレイヤーの役割整理

まず全体像から整理します。Claude Codeの設定は6つのレイヤーに分かれます。

各レイヤーの詳細は公式ドキュメントを参照してください。

Extend Claude with skills - Claude Code Docs

Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundled skills.

Claude Code Docs

Create custom subagents - Claude Code Docs

Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management.

Claude Code Docs

Connect Claude Code to tools via MCP - Claude Code Docs

Learn how to connect Claude Code to your tools with the Model Context Protocol.

Claude Code Docs

この整理にたどり着くまでに時間がかかりました。最初はRulesとSkillsの境界が曖昧で、「コーディング規約」も「PRレビューの手順」も、同じCLAUDE.mdに書いていたからです。

判断基準はシンプルで、実行を伴うかどうか、この一点です。

実行を伴わない原則・判断基準はRulesに書く（「こう振る舞ってね」）。実行を伴うワークフローはCommandsかSkillsに書く（「これをやってね」）。この軸で分けるだけで、CLAUDE.md の肥大化はかなり防げます。

実際にどう使っているか

抽象的な話だけだと伝わらないので、自分の運用を具体的に見せます。

メルマガ自動トリアージ

/digest-newsletter というコマンドで、Gmailの未読メルマガを一括処理しています。Gmail連携で未読メールを取得し、件名と冒頭テキストで簡易トリアージをかけます。重要メールは本文精読とリンク先の内容も取得した上で、必読・ネタストック・スキップの3分類に振り分け、Obsidianにダイジェストノートを自動生成します。

20通のメルマガがリンク先の深掘りも含めて1回の実行でダイジェストになります。詳しい実装は別記事で紹介しています。

Claude Code スラッシュコマンドで自動化した実例 — メルマガ未読300件を片付けるまで

Claude Codeのカスタムスラッシュコマンド /digest-newsletter を自作した実例。コマンドの最小構成・Gmail取得→本文精読→Obsidian出力の仕組み・3週間の運用データを記録する。

amaino.me

日次アナリティクス

運用中の複数サイトのGA4とGoogle Search Consoleのデータを毎日取得して、週次比較のトレンド分析をObsidianに保存しています。「先週と比べてどのページのアクセスが伸びたか」が、データを見に行かなくても手元に届きます。

Zettelkasten管理

Obsidian Vaultの知識管理をスキルに任せています。FleetingNote（走り書きメモ）→ LiteratureNote（要約）→ PermanentNote（自分の考え）という3段階の知識変換プロセスを、スキルが支援してくれます。たとえば技術記事を読んで走り書きのメモを残すと、スキルが要点を構造化した要約ノートに変換し、「この内容は以前書いた〇〇のノートと関連がある」と既存の知識との接続を提案してくれます。自分で考えて書く部分は残しつつ、整理と発見の手間を減らせる運用です。

CLAUDE.md 設計で工夫すべき3つのポイント

ここからが本題です。スキルを作ること自体は簡単ですが、「うまく動く設計」にするにはコツがあります。

1. CLAUDE.mdは目次に徹する

最初にやりがちなのが、CLAUDE.mdにコーディング規約もワークフローも判断基準も全部書くことです。

CLAUDE.mdはClaude Codeが会話の最初に毎回読み込むファイルです。ここが大きいと、AIのコンテキストウィンドウを最初から圧迫して、長い会話の後半で前半の指示を忘れる原因になります。自分はこれで何度も失敗しました。

対策は明確で、CLAUDE.mdには具体的な内容を書かないことです。ルールは .claude/rules/ に分離して、CLAUDE.mdには「詳しくはこちらを見て」というポインタだけ置きます。必要なときだけ参照される形にすれば、コンテキストを節約できます。複数プロジェクトで rules/ を分離した実例は別記事に書いています。

CLAUDE.mdの書き方：複数プロジェクトをClaude Codeで管理する実践構成

複数プロジェクトでCLAUDE.mdを運用するための設計思想と実例。グローバルrules分離・Memory活用・worktree並行作業まで、15プロジェクト管理で固まった10個のノウハウを紹介。

amaino.me

2. context: fork でコンテキストを分離する

Skills 2.0で追加された context: fork は、スキルをメインの会話とは別のコンテキストで実行する機能です。スキルの内容がサブエージェントへのプロンプトとなり、メインの会話のコンテキストを消費しません。処理が終わると、結果だけがメインに返ってきます。

これが効くのは、大量のデータを処理するスキルです。たとえばメルマガ20通を処理すると、メール本文やリンク先のコンテンツでコンテキストが膨大になります。context: fork なしだと、後半のメールを処理する頃には前半の指示を忘れている、ということが実際に起きます。

ただし注意点があります。context: fork はスキル内に具体的なタスク指示がある場合にのみ意味があります。「こういう方針で動いて」というガイドラインだけを書いたスキルをforkしても、別働隊は何をすべきかわからず空振りします。

3. allowed-tools でツールを制限する

スキルにはどのツールを使えるかを制限する allowed-tools という設定があります。

調査系のスキルにファイル編集やコマンド実行の権限まで与えると、意図しない変更をしてしまうリスクがあります。「読み取りと検索だけ」に制限すれば、安全に調査だけをさせられます。

---
name: seo-analyzer
description: サイトのSEO状態を分析する
allowed-tools: ["Read", "Grep", "WebFetch"]
---

目的に合わせて最小限の権限だけを許可する。権限管理の基本と同じ考え方です。

まず何から始めるか

もしCLAUDE.mdに何でも書いている状態なら、最初の一歩はこれです。

CLAUDE.mdに書いているワークフローを1つ、Skillsに切り出してみてください。

最小限のSKILL.mdはこれだけです。

---
name: my-first-skill
description: 何をするスキルかを具体的に書く
---

ここにワークフローの手順を書く

これを .claude/skills/my-first-skill/SKILL.md に置くだけで、/my-first-skill として呼び出せるようになります。慣れてきたら context: fork を追加してコンテキスト分離を試し、allowed-tools で権限を絞る。段階的に育てていけばいいと思います。

MCPレイヤーとの組み合わせ（GmailやDBとの連携）についてはこちらで詳しく書いています。

TypeScriptでMCPサーバーを自作する — ゼロからClaude Code接続まで

MCPサーバーをTypeScriptでゼロから自作してClaude Codeに接続する実践記録。SDK v1系の最小構成・動作確認ログ・ツール設計の判断基準、MCPとCLIスクリプトの使い分けも解説。

amaino.me