2026/03/28Claude Code

Skills活用AI活用

CLAUDE.mdとは？書き方テンプレート付き｜書きすぎが逆効果な理由【2026年最新】

CLAUDE.mdは、Claude Codeが毎回起動時に自動で読み込む「常駐指示書」です。正しく設計すればAIの出力品質が劇的に上がりますが、書きすぎると逆に精度が落ちるという落とし穴があります。

この記事では、実際の運用経験をもとにCLAUDE.mdの最適な書き方、4階層のスコープ、.claude/rules/やMemory機能との使い分け、そして「お願い」であるCLAUDE.mdと「強制」であるHooksの線引きまで解説します。

CLAUDE.mdとは何か？——Claude Codeの「記憶」を支えるファイル

CLAUDE.mdは、Claude Codeの起動時に自動的にコンテキストへ追加されるMarkdownファイルです。プロジェクトのルール、技術スタック、禁止事項などを記述しておくことで、毎回プロンプトに書かなくても一貫した指示を与えられます。

一言で言えば、新しく入ったメンバーに渡すオンボーディング資料のようなものです。ただし読むのはAIなので、人間向けの冗長な説明は不要。簡潔に、正確に書くことが重要です。

一般的な使い方としては、以下のような情報を記載します。

使用している言語・フレームワーク・バージョン
コーディング規約（命名規則、インデント、import順など）
セキュリティ系の禁止事項（.envのコミット禁止、本番DBへの直接操作禁止など）
テスト方針やディレクトリ構成の概要

/init コマンドで自動生成できる

白紙から書く必要はありません。Claude Codeで/initコマンドを実行すると、プロジェクトの構成（package.json、設定ファイル、ディレクトリ構造など）を解析して、CLAUDE.mdの初期版を自動生成してくれます。これをベースにカスタマイズするのが効率的です。定期的に/initを実行して現状のCLAUDE.mdと比較し、不要な記述を削除するメンテナンスも効果的です。

CLAUDE.mdの4階層を理解する

CLAUDE.mdには4つのスコープ（適用範囲）があります。これを理解することが、効果的な設計の第一歩です。

CLAUDE.mdのスコープ階層図（ユーザー・プロジェクト・ディレクトリ・ローカル）

1. ユーザーレベル（~/.claude/CLAUDE.md）

ホームディレクトリの.claude/配下に置くCLAUDE.mdは、すべてのプロジェクトに共通で適用されます。「日本語で回答する」「コミットメッセージは日本語で書く」など、個人の好みに関するルールを書く場所です。

2. プロジェクトルート（./CLAUDE.md）

最も一般的な配置場所です。プロジェクトのルートに置き、チーム全体で共有します。Gitにコミットすることで、チームメンバー全員が同じコンテキストでClaude Codeを使えます。

3. ディレクトリ別（./backend/CLAUDE.md など）

サブディレクトリに置くCLAUDE.mdは、Claude Codeがそのディレクトリのファイルにアクセスしたときにオンデマンドで読み込まれます。モノレポ構成でフロントエンドとバックエンドの規約が異なる場合などに有効です。

4. ローカルオーバーライド（./CLAUDE.local.md）

.local.mdはgitignore対象の個人設定です。「自分だけ使うMCPサーバーの情報」「自分のローカル環境固有のパス」など、チームに共有する必要のない設定を書きます。

これら4階層は起動時に上位から順に結合され、1つのコンテキストとしてClaudeに渡されます。より具体的な階層の記述が優先されるため、ユーザーレベルで「英語で回答」と書いていても、プロジェクトルートで「日本語で回答」と書けばプロジェクト内では日本語になります。

書きすぎると逆効果になる理由

ここが最も重要なポイントです。CLAUDE.mdに情報を詰め込みすぎると、AIの精度がかえって低下します。

Stanford大学とUC Berkeleyの2023年の研究「Lost in the Middle」によれば、LLM（大規模言語モデル）は長いコンテキストの中間部分の情報を見落としやすいことが実証されています。先頭と末尾の情報は比較的正確に処理される一方、中間部分では精度が50〜60%にまで低下するケースが報告されています。

CLAUDE.mdが長くなればなるほど、この「中間の見落とし」が発生するリスクが高まります。重要なルールを書いていたのに無視される——その原因は、CLAUDE.mdの情報量が多すぎることかもしれません。

Anthropic公式も、CLAUDE.mdは200行以下（最大でも300行程度）に収めることを推奨しています。「CLAUDE.mdは短いほど良い」と明記されており、重要なルールが他の記述に埋もれないことが最も大切です。

書くべきこと・書くべきでないこと

では、限られた行数の中で何を書き、何を外に出すべきなのか。判断基準は「毎回のセッションで必ず参照すべき情報か？」です。

書くべきこと

プロジェクトの概要: 1〜2行で何のプロジェクトかを説明（「Next.js App Router製のコーポレートサイト」など）
ビルド・テスト・実行コマンド: npm run dev、npm run test、npm run buildなど
ディレクトリ構造: 主要なディレクトリと役割の一覧
コーディング規約のポイント: 言語・フレームワーク固有の方針（「サーバーコンポーネントをデフォルトとする」等）
やってはいけないこと: 禁止事項は明確に書く（「.envファイルをコミットしない」「本番DBに直接アクセスしない」等）

書くべきでないこと

コードを読めばわかること: ファイル内のインポート順序やインデント幅など、既存コードから推測できる規約
長い説明文や背景情報: CLAUDE.mdは簡潔であるほど効果的。長い説明が必要なら別ファイルに分割し、CLAUDE.mdからはパスだけ記述
頻繁に変わる情報: 現在のスプリントの内容や一時的なタスクリスト
Claude Codeがデフォルトでやること: 正しく動作している挙動をわざわざ記述すると、ファイルが無駄に長くなる

手順書レベルの詳細な作業フローは、Skills機能に分離するのが正解です。Skillsは必要なときだけ呼び出されるため、常駐コンテキストを圧迫しません。

.claude/ディレクトリとの連携

CLAUDE.mdと合わせて理解しておくべきなのが、.claude/ディレクトリです。これはClaude Codeのプロジェクト設定を格納するフォルダで、CLAUDE.mdと役割が異なります。

.claude/rules/ — モジュール化されたルール

CLAUDE.mdを200行以内に収めるための強力な手段が、.claude/rules/ディレクトリです。Claude Codeは.claude/rules/配下のMarkdownファイルを自動的にコンテキストへ追加します。関心事ごとに分割したルールファイル（.md形式）を配置し、1ファイル1テーマで管理するのが推奨パターンです。

私のプロジェクトでは以下のようにルールを分離しています。

.claude/rules/article-writing.md — 記事の表記ルール（一人称、SEO、プライバシー保護）
.claude/rules/coding.md — コーディング規約（命名、CSS変数、画像キャッシュ）
.claude/rules/business-context.md — サービス体系・料金・ビジネス方針

CLAUDE.md本体にはプロジェクトの概要とディレクトリ構成だけを書き、詳細ルールはrules/に分離する。これで常駐コンテキストの肥大化を防ぎつつ、必要なルールは確実に読み込まれます。

.claude/commands/ — カスタムスラッシュコマンド

.claude/commands/にマークダウンファイルを置くと、独自のスラッシュコマンドを定義できます。たとえばdeploy.mdを置けば、/deployでデプロイ手順をClaude Codeに実行させられます。

.claude/skills/ — 自動実行されるワークフロー

Skillsは、SKILL.mdに定義した条件に合致するタスクを受けたとき、Claude Codeが自動的に読み込んで実行するワークフローです。「SEO記事を書いて」と言うだけで、キーワード調査→執筆→画像生成→CMS投稿まで一気に実行する——この記事自体もSkillを使って書かれています。

.claude/settings.json — 権限と動作設定

Permissions（allow/deny）やHooksの設定を記述するJSONファイルです。CLAUDE.mdが「何をすべきか」を伝えるのに対し、settings.jsonは「何をしてよいか」を制御します。

Skillsとの違いは「常に読み込まれるか、呼び出し時だけか」です。rules/は全セッションで常に適用されるルール。Skillsは特定タスクの実行時だけ読み込まれる手順書です。

Memory機能との使い分け

Claude Codeには、セッション間で情報を引き継ぐMemory機能もあります。CLAUDE.mdとの使い分けを整理しましょう。

機能	性質	書くべき内容
CLAUDE.md	固定的・宣言的	技術スタック、コーディング規約、禁止事項
.claude/rules/	固定的・モジュール化	分野別の詳細ルール（記事執筆、コーディング等）
Memory	可変的・蓄積型	ユーザーの好み、過去のフィードバック、プロジェクト状況
Skills	オンデマンド	特定タスクの作業手順（記事生成、デプロイ等）

ポイントは、変わらない情報はCLAUDE.md/rulesに、変わる情報はMemoryに置くことです。「テストにモックを使うな」のような恒久的なルールはrules/に書き、「前回のセッションでユーザーがこの方針を好んだ」といった学習はMemoryに蓄積させます。

この4層構造を意識することで、CLAUDE.mdの肥大化を防ぎつつ、Claude Codeに必要な情報を過不足なく渡せます。

CLAUDE.mdは「お願い」、Hooksは「法律」

実運用で最も重要なのが、この使い分けです。CLAUDE.mdに書いた内容は、Claude Codeに対する「お願い」や「ガイドライン」であり、100%遵守される保証はありません。Anthropic公式も「約80%の精度で従う」と明記しています。

絶対に守らせたいルール——たとえば「特定のファイルを編集させない」「コミット前にテストを実行する」——は、CLAUDE.mdではなくHooksで制御すべきです。Hooksはsettings.jsonに設定するスクリプトで、ツールの実行前後に確実に実行されます。

CLAUDE.mdが「方針」、Hooksが「法律」——この使い分けが、実務では非常に重要です。

私自身、CLAUDE.mdに「robots.txtを変更しない」と書いていたのに、AIが独断で変更してしまったインシデントがありました。CLAUDE.mdに書いていた禁止事項が、実際には守られなかったのです。以降、この種の重要ルールはHooksとPermissions（deny設定）で強制するようにしています。書いても従わないかもしれない——その前提で設計することが、実運用では不可欠です。

実運用：あえて書き込まない方針

私自身のCLAUDE.md運用は、「必要最小限」を徹底しています。

以前はデザイン系MCP（Model Context Protocol）をCLAUDE.mdで設定し、あらゆる指示を常駐させていました。しかし、コンテキストが膨らむにつれてClaudeの応答精度が下がり、意図しない出力が増えたのです。

そこで、デザイン系MCPを外し、.claude/rules/ + Skills方式に切り替えました。CLAUDE.md本体はプロジェクト概要・ディレクトリ構成・外部参照の3セクションだけ。コーディング規約は.claude/rules/coding.mdに、記事の表記ルールは.claude/rules/article-writing.mdに分離しています。

結果として、Claudeの応答がシャープになり、指示の遵守率が体感で大きく改善しました。「書けるからといって全部書く」のではなく、「書かないことで精度を上げる」という逆転の発想が重要です。

CLAUDE.mdは50〜80行程度に収め、詳細ルールは.claude/rules/に4〜5ファイル配置する。最初は「あれもこれも」と書きたくなりますが、数週間運用すると「Claude Codeが既にわかっていること」と「明示的に伝えないとズレること」の区別がつくようになります。

効果的なCLAUDE.mdの書き方テンプレート

実際に使えるテンプレートの構成例を紹介します。

セクション	内容	目安行数
Overview	プロジェクトの概要（何を、誰のために）	5〜10行
技術スタック	言語、フレームワーク、主要ライブラリ、バージョン	10〜20行
ディレクトリ構成	主要フォルダの役割（ツリー形式）	15〜25行
禁止事項	セキュリティ系NG、やってはいけない操作	5〜10行
ルール参照	.claude/rules/内の各ファイルへの参照	5〜10行
頻出コマンド	ビルド、テスト、デプロイのコマンド	5〜10行