CLAUDE.mdの書き方: 2026年版 完全ガイド（Q2公式ベストプラクティス反映版）

Claude Codeを使っているなら、今すぐできる最もインパクトの大きなことのひとつが、良いCLAUDE.mdファイルを書くことだ。これはコードベース向けのシステムプロンプトだ。Claude Codeがプロジェクトを開く度にCLAUDE.mdを最初に読み、その後の全ての作業がそこで見つけた内容に影響される。

このガイドでは、CLAUDE.mdとは何か、なぜ重要なのか、どう構成するか、そして優れたOSSプロジェクトがどんなパターンを使っているかを解説する。全ての例は実際のリポジトリから来ている。

CLAUDE.mdとは？

CLAUDE.mdはリポジトリのルート（またはサブディレクトリ）に置くMarkdownファイルで、Claude Codeにプロジェクトについての永続的な指示を提供する。人間の開発者向けではなく、AIコーディングアシスタント向けに書かれたREADMEだと思えばいい。

CLAUDE.mdファイルを含むディレクトリでClaude Codeを起動すると、Claudeはセッション開始時に自動でそれを読む。消えてしまう会話コンテキストと違い、CLAUDE.mdは永続する。常にそこにあり、常に読み込まれ、常にClaudeの動作に影響している。

AnthropicはCLAUDE.mdをClaude Codeのエージェント型コーディングワークフローの一部として導入した。それ以来、.cursorrulesやAGENTS.mdと並んでAIコーディング設定の最も広く採用された標準のひとつになっている。

CLAUDE.mdが重要な理由

CLAUDE.mdなしでは、Claude Codeはプロジェクトについて合理的な推測をする。あれば、正確な規約に従い、不要なパターンを避け、最初から自分のコードベースに合ったコードを生成できる。

しっかり書かれたCLAUDE.mdが除去するもの：

• 繰り返しの修正。 「シングルクォートを使って」「クラスを使わないで」と何度も言うなら、それはCLAUDE.mdに書くべきだ。
• スタイルの不一致。 フォーマット規約、命名パターン、インポート順序をCLAUDE.mdで指定すればClaudeが自動で従う。
• 間違ったアーキテクチャの決定。 好みのパターン（例：クライアントコンポーネントよりサーバーコンポーネント）を伝えれば、それをデフォルトにする。
• コンテキストウィンドウの無駄。 毎セッション同じプロジェクトの説明を繰り返す代わりに、CLAUDE.mdが一度で全て処理する。

Vercel Next.jsのCLAUDE.md（138Kスター）が完璧な例だ。モノレポ構造から優先テストフレームワークまで全てを指定していて、コントリビューターたちがClaudeに従わせた時のレビューサイクルが劇的に減少したと報告している。

ファイルの配置と階層

CLAUDE.mdファイルは複数のレベルに置ける：

• リポジトリルート（/CLAUDE.md）— プロジェクトの全セッションで読み込まれる。プロジェクト全体のルールを書く場所。
• サブディレクトリ（/packages/api/CLAUDE.md）— そのディレクトリでClaudeが作業する時だけ読み込まれる。モノレポのパッケージ固有のルールに使う。
• ユーザーレベル（~/.claude/CLAUDE.md）— 自分が作業する全プロジェクトで読み込まれる。エディタ設定やフォーマットの好みなど個人的な設定に最適。

Claudeは順番に読む：ユーザーレベルが最初、次にルート、次にサブディレクトリ。より具体的なファイルが優先される。

効果的なCLAUDE.mdの構成

The Prompt Shelfのトップリポジトリの数十のCLAUDE.mdファイルを分析すると、明確なパターンが見えてくる。優れたファイルは以下のセクションを持っている：

1. プロジェクト概要

プロジェクトの説明と技術スタックの簡単な記述から始める。これがClaudeにアーキテクチャの意思決定のためのコンテキストを与える。

# Project

This is a Next.js 14 application using the App Router, TypeScript,
Tailwind CSS, and Drizzle ORM with PostgreSQL.

LangChainのCLAUDE.mdはプロジェクトの目的とコアな抽象化の明確な説明で始まっている。Claudeがコードを書く前にドメインを理解するためだ。

2. コードスタイルと規約

ここが最も時間を節約するセクションだ。具体的かつ処方的に書こう。

## Code Style

- Use functional components with arrow functions
- Prefer named exports over default exports
- Use TypeScript strict mode; no `any` types
- Imports: React first, then third-party, then local (with blank lines between groups)
- File naming: kebab-case for files, PascalCase for components

Excalidrawのサンプルは、フォーマットだけでなくコンポーネント合成パターンや状態管理のアプローチなどアーキテクチャの好みまで特に詳しく書いている。

3. アーキテクチャとパターン

どのパターンを好み、どれを避けるかをClaudeに伝える。

## Architecture

- Server Components by default; only use 'use client' when necessary
- Data fetching happens in Server Components, never in client components
- Use Server Actions for mutations
- Keep components small; extract to separate files at ~50 lines

Dan Abramov / OverreactedのCLAUDE.mdは、コードベースの一貫性を保つ強いアーキテクチャ上の主張のエンコード方法を示している。

4. プロジェクト固有のコマンド

プロジェクトに特殊なビルド手順、テストコマンド、開発ワークフローがあれば記載する。

## Commands

- `pnpm dev` — Start development server
- `pnpm test` — Run Vitest in watch mode
- `pnpm lint` — ESLint + Prettier check
- `pnpm db:push` — Push schema changes to database

DenoのCLAUDE.mdはビルドとテストの詳細な指示を含んでいる。プロジェクトが非標準のビルドシステムを使っていて、Claudeが他では知る方法がないからだ。

5. やってはいけないこと

否定の指示は意外なほど効果的だ。避けるべきことを伝えるのは、すべきことを伝えるより効果的なことが多い。

## Do NOT

- Do not use `class` components
- Do not use `any` type
- Do not add dependencies without asking
- Do not modify the database schema directly
- Do not use inline styles

CockroachDBのCLAUDE.mdには、Claudeが変更すべきでないサブシステムと避けるべきテストパターンについての明示的な制約がある。

6. ファイル構成

大規模なプロジェクトでは、どこに何があるかをClaudeに伝える。

## File Structure

- `src/components/` — Reusable UI components
- `src/app/` — Next.js App Router pages
- `src/lib/` — Utility functions and shared logic
- `src/db/` — Database schema and migrations

7. テストの期待値

テストをいつ・どのように書くかを指定する。

## Testing

- Every new component needs a test file in __tests__/
- Use Testing Library for component tests
- Use Vitest, not Jest
- Integration tests go in tests/integration/
- Run `pnpm test:unit` before committing

参考になる実例

The Prompt Shelfで見られる注目プロジェクトのCLAUDE.mdを紹介する：

Vercel Next.js — モノレポのCLAUDE.mdのゴールドスタンダード。詳細なテストとコントリビューションガイドラインを含むNext.jsフレームワーク全体のコードベースをカバー。138Kスター。

LangChain — 複数パッケージを持つ複雑なPythonライブラリのドキュメント化方法を示す。インポート規約とテストパターンを重視。128Kスター。

Excalidraw — Reactアプリケーションの良い例。コンポーネントパターン、状態管理、UI規約を指定。118Kスター。

Deno — RustベースのランタイムのCLAUDE.mdを示す。ビルドシステムの癖とクロスプラットフォームの考慮事項をカバー。106Kスター。

Zed Editor — GPUIフレームワークを使ったRustアプリのCLAUDE.mdの書き方を示す。カスタムUIフレームワークについての詳細な説明を含む。76Kスター。

Anthropicの公式ガイド — CLAUDE.mdについてのAnthropicの推奨事項。簡潔で原則に基づく。

Freek Van der Herten / Spatie Laravel — PHP/Laravelプロジェクトの優れた例。CLAUDE.mdがJavaScriptエコシステム以外でも機能することを示す。

ベストプラクティス

数百のCLAUDE.mdファイルをレビューした結果、一貫して良い結果を出すパターン：

具体的に、抽象的にならない。 「スタイリングにTailwind CSSを使う」は「モダンなCSSプラクティスに従う」より良い。「条件付きクラスには@/lib/utilsのcn()を使う」はさらに良い。

500行以内に収める。 ClaudeはセッションごとにファイルのBotomを読む。長すぎると重要なルールが薄まる。詳細なドキュメントは別ファイルに移して参照する。

例を使う。 プロジェクトで良いコードがどう見えるかをClaudeに見せる。5行のコードサンプルは50行の説明より価値がある。

定期的に更新する。 CLAUDE.mdはコードベースと共に進化すべきだ。同じことでClaudeを繰り返し修正しているなら、そのファイルに追加しよう。

ルールをテストする。 CLAUDE.mdを変更した後、新しいClaudeセッションを開始して一般的なタスクを実行させる。新しいルールに従っているか確認する。

READMEと重複させない。 CLAUDE.mdはAI固有の指示のためのものだ。人間の開発者には必要だがClaudeには不要なセットアップ手順はREADME.mdに置く。

モノレポはサブディレクトリファイルを使う。 20パッケージのモノレポのための1つの巨大なCLAUDE.mdは、ルートファイルに共通のルール＋パッケージ固有のファイルより効果的ではない。

CLAUDE.md vs 他のフォーマット

CLAUDE.mdはClaude Code専用だ。チームが複数のAIツールを使うなら、以下も必要かもしれない：

• .cursorrules — Cursor AI向け。同様のコンセプト、異なるフォーマット。
• AGENTS.md — マルチエージェントシステムの広範な標準。Codex、Claude Code、その他で使用。
• .github/copilot-instructions.md — GitHub Copilot向け。

良いニュースは、これらのフォーマットは十分似ているので、1つの正典ドキュメントを維持して適応できる。詳細な比較は比較ガイドを参照。

トークンコスト：サイズが重要な理由（2026 Q2 アップデート）

CLAUDE.mdオーサリングで最も指摘されるミスは 過剰仕様化。Anthropicの公式ベストプラクティスガイドが直球で述べている：“Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”（肥大化したCLAUDE.mdはClaudeに実際の指示を無視させる！）

頭に叩き込むべき3つの数字：

これが HumanLayer のガイド が 300行未満を soft cap として推奨 し、彼らの本番ルートCLAUDE.mdが60行未満である理由。レバレッジは双方向に効く — 良い1行は毎セッションを引き上げ、悪い1行は毎セッションを毒する。

肥大化を疑うなら、簡単なテスト：Claude Codeに「CLAUDE.mdを1段落で要約して」と頼んでみる。Claude が省略・抽象化してしまった部分は、モデルが既に低優先度扱いしている部分。

Anthropic 公式 Include/Exclude 表

Anthropicの公式ベストプラクティスドキュメントが、CLAUDE.mdに何を入れるかの判断テーブルを公開している。Anthropicがこの問題に対して公にした最も明確な意見であり、ほとんどのエッジケースをカバーしている：

Includeコラムは同じ原則に基づく：Claudeがコードから導けない情報だけを書く。npm run lint --help で置換可能な行は削除する。linterルールで置換可能な行は削除して、ルールを書く。「Never send an LLM to do a linter’s job」（リンターの仕事をLLMに送るな）— HumanLayer の言い方 — がこの非対称性を端的に表す。

残したルールの adherence を強化するには、強調トークンの追加が有効：“IMPORTANT” または “YOU MUST” を高ステーク・ルールの前につけると、Claudeが遵守する頻度が測定可能に改善する。本当に高ステークなルールに限定すること。全部に「IMPORTANT」をつけたら、どれもIMPORTANTでなくなる。

@import パターン：モジュラー CLAUDE.md

単一の巨大なCLAUDE.mdは、玩具サイズを超えたプロジェクトには間違った形。Claude Code は CLAUDE.md 内で @path/to/import 構文をサポートしていて、小さなルートファイルを複数のターゲットファイルから組み立てられる：

# プロジェクトルート CLAUDE.md
@README.md でプロジェクト概要、@package.json で npm コマンド一覧を参照。

# コードスタイル
- TypeScript strict モード使用
- 詳細規約: @docs/style-guide.md

# ワークフロー
- Git workflow: @docs/git-instructions.md
- 個人オーバーライド: @~/.claude/my-project-instructions.md

import はセッション開始時に解決される。実用的なメリット：

• 大きなドキュメントをルート外に逃がす — ルートCLAUDE.mdを60-100行未満に保ち瞬時にスキャン可能、詳細はimportに押し出す
• 開発者ごとのオーバーライド — @~/.claude/my-project-instructions.md で各開発者がチーム共有ファイルを汚さずに個人設定追加
• モノレポ構成 — ルート CLAUDE.md が各パッケージの packages/foo/CLAUDE.md を import
• Skill 隣接の永続化 — workflow specs を import 可能なファイルに置けば、CLAUDE.md からも ad-hoc プロンプトからも参照できる

@import を下記の配置ルール（home / project root / .local.md / parent / child）と組み合わせれば、コンテキスト制御の粒度を細かくできる。

CLAUDE.md vs Skills：どちらを使うか

Claude Code v2.0 以降、Skills がドメイン知識・再利用可能ワークフローの推奨置き場所になっている。Anthropic ドキュメントの判断ルール：

“CLAUDE.mdは毎セッションロードされるので、広く適用される内容のみを含めるべき。時々しか関連しないドメイン知識やワークフローは、Skills を使う。Claude が必要に応じて on demand でロードし、毎回の会話を肥大化させない。”

具体例：

判断の rule of thumb：毎セッション コンテキストにロードしたい内容なら CLAUDE.md。ユーザーが明示的にワークフロー起動 or トピック質問した時だけ関連するなら Skill。Skills 全般の解説は 2026年インストールすべき Claude Code Skills ベスト15 を参照。

CLAUDE.md を「コードとして扱う」

Anthropic ドキュメントは明示する：“Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude’s behavior actually shifts.”（CLAUDE.md はコードとして扱う：問題が起きたらレビュー、定期的に剪定、変更時はClaudeの挙動が実際に動いたか観察する）。これが意味する保守サイクルを多くのチームがスキップしている：

レビュー：CLAUDE.md にルールがあるのに Claude が望まない動作を繰り返すなら、ファイルが長すぎてルールが埋もれている可能性が高い。CLAUDE.md に答えがあるのに Claude が質問してくるなら、文言が曖昧。両方とも「ルールを足す」のではなく「剪定 or 言い換え」のシグナル。

剪定：四半期ごとにファイルを1行ずつ歩いて自問する：「この行を消したら Claude がミスするか？」。しないなら削除。多くのチームは CLAUDE.md 開始から半年以内に 30-50% の死荷重を蓄積する — 古いコマンド、古いスタイルルール、もう該当しない gotcha。

テスト：挙動変更をデプロイのように扱う。CLAUDE.md を編集したら、代表的タスクを実行して Claude の挙動が意図通りシフトしたか観察する。シフトしないなら編集は効いていない — 通常はボリュームでルールが埋もれたか、文言が曖昧。

バージョン管理：CLAUDE.md は git に入れる。コードと同じく PR レビューで変更管理。チーム共有 CLAUDE.md は時間とともにプロジェクト固有 gotcha の蓄積で価値が増す。

2026 本番チームの実例ベース・アンチパターン

Anthropic と高頻度 Claude Code 利用ショップ（HumanLayer 等）が最も指摘するパターン：

1. キッチンシンク CLAUDE.md — プロジェクト関連の全知識を放り込んで500行超え。Claude は下3分の1を無視。修正：徹底剪定 + @import で詳細ファイル分離。
2. リンタールールに偽装した指示 — 「2スペースインデント使用」は .prettierrc に書くべきで、CLAUDE.md ではない。ツールで強制可能な行は全部ツールに任せる。
3. 頻繁に変わる事実 — 「現在 sprint 47」は1週間で間違いになる。CLAUDE.md は半永続的なコンテキストのみ。
4. 守備的な過剰仕様化 — 「ビルドを壊すな」「セキュリティ脆弱性を入れるな」。自明。スペースを取って信号を増やさない。
5. ホットフィックスの居残り — 昨日のバグ修正用に追加したルール。バグは修正済み。ルールはノイズ化。ホットフィックスは temporary に — commit メッセージに移すか、根本問題が解決したら削除。
6. ファイルごとのドキュメント — 「auth.ts がログイン、user.ts がユーザーデータ」 — Claude が自分で読める。CLAUDE.md でのファイル別 docs はほぼ常にトークンの無駄。
7. /init 生成結果の放置 — /init はスターターを出力するのであって完成品ではない。/init 出力を未編集で出荷したチームは肥大化したジェネリックファイルに陥る。/init はスキャフォルディング扱い、その後徹底剪定する。

始め方

まだCLAUDE.mdがないなら、小さく始めよう：

1. プロジェクトルートにCLAUDE.mdファイルを作成する。
2. プロジェクトの1段落の説明を追加する。
3. 最も重要なコーディング規約5つをリストアップする（デフォルトと異なるもののみ）。
4. Claudeに絶対にやってほしくないこと3つを追加する（非自明なもののみ）。
5. 最もよく使う開発コマンドを含める（Claudeが推測できないもののみ）。

それだけで目に見える改善がある。ルートは60-100行未満を目標に。ドキュメントが必要なパターンを発見しながら @import モジュールでファイルを拡張する。四半期ごとに再読し、もう価値のない行を削る。

インスピレーションを探すならCLAUDE.mdファイルの全コレクション、または他のプロジェクトがAIコーディングアシスタントをどう設定しているかを見るなら全ルールギャラリーを参照。

FAQ

CLAUDE.md はどのくらいの長さにすべき？

ハードリミットはないが、300行未満が有用な soft cap、ルートファイルは60-100行未満が sweet spot。HumanLayer の本番ルート CLAUDE.md は60行未満で同基準を推奨。300行超えると ~150-200 のフロンティアモデル指示追従能力の天井にあたり、ファイル末尾のルールが silently 無視されるリスクが出てくる。大規模プロジェクトには @import で詳細を組み立て可能なモジュールに分割する。

CLAUDE.md と Skills の違いは？

CLAUDE.md は 毎セッション 開始時にコンテキストにロードされるので、広く適用されるルールのみ。Skills（.claude/skills/<name>/SKILL.md）は on demand でロード — Claude が現在のタスクに関連と判断した時、または /skill-name で明示起動した時。常に関連するプロジェクトルール（コマンド、スタイル、gotcha）は CLAUDE.md、時々関連するドメイン知識（resolver 追加方法、マイグレーション runbook 等）は Skills。

CLAUDE.md はどこに置ける？

5つの正規場所、全て関連時に自動ロードされる：(1) home フォルダ ~/.claude/CLAUDE.md（全プロジェクトの全セッションに適用）、(2) プロジェクトルート ./CLAUDE.md（git に入れる、チーム共有）、(3) プロジェクトルート ./CLAUDE.local.md（個人、gitignore）、(4) モノレポ用の親ディレクトリ、(5) on demand でロードされる子ディレクトリ（そのディレクトリ内ファイル作業時）。

@import 構文はどう動く？

任意の CLAUDE.md 内で @path/to/file.md と書くと、そのファイルの内容がセッション開始時にインライン展開される。import は相対パス（@docs/style-guide.md）、絶対パス（@/Users/me/.claude/overrides.md）、home 相対（@~/.claude/my-project-instructions.md）すべて可。ルート CLAUDE.md を短く保ちつつ、関心事ごとに詳細を import で持ち込めるパターン。

CLAUDE.md で「IMPORTANT」や「YOU MUST」を使うべき？

本当に高ステークなルールには Yes。Anthropic ドキュメントによれば、IMPORTANT や YOU MUST のような強調トークンは adherence を測定可能に改善する — ただし本当に重要なルールに限定した場合のみ。全ルールが「IMPORTANT」なら、どれも IMPORTANT でなくなる。セキュリティ境界、破壊操作防止、不可逆アクション guardrail に使う、スタイル選好には使わない。

/init の出力を CLAUDE.md にそのまま含めるべき？

/init は開始点として使い、徹底剪定する。/init コマンドはコードベースを解析して plausible なスターターを生成するが、verbose 寄りで、Claude がコードから導けるファイル単位の説明や標準規約まで含めがち。/init 出力を未編集で出荷したチームは肥大化したファイルに陥る。HumanLayer は明示的に /init 出力のそのまま使用を推奨しない。

CLAUDE.md は Claude 以外のツールでも動く？

CLAUDE.md は Claude Code 専用。マルチツールチームには、クロスツール標準として AGENTS.md（Codex / Claude Code 等で利用、AGENTS.md vs CLAUDE.md ガイド 参照）、.cursor/rules/（Cursor）、.windsurf/rules/（Windsurf）、.github/copilot-instructions.md（Copilot）。コンテンツの重複が大きいため、1つの正典を維持して各形式に適応可能。Caveman.MD のようなツールは圧縮ルールを同時に複数フォーマットに drop する。

CLAUDE.md はどのくらいの頻度で更新すべき？

四半期レビューを最低限とする。具体的には：(1) ルールが防ぐはずの動作を Claude が繰り返したら — ルールがノイズに埋もれている可能性大、剪定 or 言い換え、(2) CLAUDE.md に答えがあるのに Claude が質問してきたら — 文言が曖昧、書き直し、(3) プロジェクト規約変更時 — 新規約追加と旧規約削除を同編集で、(4) 四半期に1度ファイルを1行ずつ歩いて 「この行を消したら Claude がミスするか？」 と自問、しないなら削除。

関連記事

• AGENTS.md vs CLAUDE.md 決定版比較
• .cursorrules vs CLAUDE.md vs AGENTS.md（3方比較 2026）
• 2026年インストールすべき Claude Code Skills ベスト15
• Claude Code Subagents 完全リファレンス 2026
• Claude Code Hooks 本番リファレンス 2026
• Caveman.MD: AIコーディングエージェントのトークン圧縮
• AGENTS.md ベストプラクティス 2026
• 165以上のAIコーディングルール実例集

外部参考

• Claude Code: Best practices（公式） — Anthropic の権威ガイド、Include/Exclude 表の出典
• Claude Code: Memory（公式） — CLAUDE.md 配置の正規仕様
• Writing a good CLAUDE.md（HumanLayer） — 本番チームの視点