CLAUDE.mdベストプラクティス｜書き方・設定例・チーム運用のコツを解説
Claude Codeを使い始めたものの、「毎回同じ前提条件を伝え直すのが面倒」「指示したはずのルールをClaudeが守ってくれない」「CLAUDE.mdが肥大化して何が書いてあるかわからない」。こうした悩みを抱えている開発者は少なくありません。
CLAUDE.mdは、Claude Codeが毎セッションの冒頭に自動で読み込む設定ファイルです。プロジェクトのコーディング規約、ビルドコマンド、禁止事項などを記述しておくことで、チャットで毎回伝える手間をなくし、Claudeの動作を安定させることができます。しかし、書き方を間違えると逆効果になることもあり、「何を書くべきか」「何を書くべきでないか」の線引きが重要です。
この記事では、Anthropic公式ドキュメントとコミュニティの実践知をもとに、CLAUDE.mdの基本構造から、書くべき内容と書くべきでない内容の判断基準、階層構造と分割設計、実務で効果のある設定例、チーム運用と定期メンテナンスのコツまで、体系的に解説します。
| 確認したいポイント | 結論 | 詳細 |
| CLAUDE.mdとは何をするファイル？ | セッション開始時に自動で読み込まれる指示ファイル | コーディング規約やビルドコマンドなどを記述しておくことで、Claudeの動作を安定させる仕組み |
| 何を書くべき？ | Claudeがコードから推測できないことだけ | ビルド手順、テスト実行方法、プロジェクト固有の規約、過去の失敗から得た教訓などに限定する |
| 行数の目安は？ | 公式推奨200行以内、実務では60行前後が最適 | 行数が多いほど各指示の効果が薄れるため、必要最小限に絞り込むことが重要になる |
| チームでどう管理する？ | Gitで管理し、月1回の定期見直しを行う | プロジェクト共有はGitコミット、個人設定はCLAUDE.local.mdに分離してgitignoreする |
| この記事でわかること ・CLAUDE.mdの役割と、セッション開始時の読み込みの仕組み ・書くべき内容と書くべきでない内容の具体的な判断基準 ・グローバル・プロジェクト・ローカルの3階層と、.claude/rules/による分割設計 ・コーディング規約・ワークフロー・セキュリティなど実務で効果のある設定例 ・チーム開発でのGit管理と定期メンテナンスの運用フロー |
| AIエージェントの導入事例や、PoCから本番化までの進め方をまとめた資料を無料でダウンロードいただけます。Claude Codeの活用を検討されている方は、ぜひご覧ください。 ▶ 資料請求フォームはこちら |
CLAUDE.mdとは？役割と読み込みの仕組み
CLAUDE.mdは、Anthropic社が提供するClaude Codeが毎セッションの開始時にコンテキストウィンドウへ自動で読み込むMarkdownファイルです。Anthropic公式ドキュメントでは「Claudeに永続的なコンテキストを与えるための指示ファイル」と位置づけられています。
メモリシステムにおけるCLAUDE.mdの位置づけ
Claude Codeのメモリシステムは複数の階層で構成されており、CLAUDE.mdはその中核を担う要素です。セッションが開始されるたびに、ルートディレクトリから現在の作業ディレクトリまでのCLAUDE.mdが自動的に読み込まれ、Claudeの動作に反映されます。
ここで重要なのは、CLAUDE.mdはコンテキストウィンドウに読み込まれる「参考情報」であり、強制設定ではないという点です。Hooksのような確実な実行保証はなく、Claudeが「参考にする」ものとして扱われます。だからこそ、少なく・具体的に・検証可能な形で書くことがベストプラクティスの出発点となります。
また、CLAUDE.mdに書いた内容は毎回トークンを消費します。つまり、不要な記述を残しておくこと自体がコストの増加要因になります。グローバルCLAUDE.md（~/.claude/CLAUDE.md）に書いた内容は、どのプロジェクトで作業していても毎セッション読み込まれるため、本当に全プロジェクトに共通する内容のみに限定すべきです。
CLAUDE.mdと混同されやすい概念に「Auto Memory（自動メモリ）」があります。これはClaudeがセッション中に「#で始まるメモリコマンド」を検知した際に自動保存される記憶で、ユーザーの好みやプロジェクトの学習内容を蓄積します。CLAUDE.mdが「開発者が意図的に設計する指示書」であるのに対し、Auto Memoryは「Claudeが会話の中から自動的に抽出する学習結果」という位置づけです。両者を併用することで、明示的なルールと暗黙的な学習の両方をカバーできます。
なお、他のAIコーディングツールにも類似の仕組みがあり、OpenAI CodexにはAGENTS.md、Cursorには.cursorrulesという対応するファイルが存在します。CLAUDE.mdの設計思想を理解しておけば、ツールを横断して応用可能な知識となります。
CLAUDE.mdの4つの配置場所と優先順位
CLAUDE.mdは4つの階層に配置でき、それぞれ異なるスコープで機能します。
1つ目はグローバル設定（~/.claude/CLAUDE.md）で、すべてのプロジェクトに適用されるユーザー個人の設定です。言語設定や作業スタイルの好みなど、プロジェクトに依存しない内容を記述します。
2つ目はプロジェクト設定（プロジェクトルート/CLAUDE.md）で、チーム全員に共有されるプロジェクト固有の設定です。Gitにコミットすることで、メンバー間でルールを統一できます。
3つ目はローカル設定（CLAUDE.local.md）で、プロジェクト単位の個人設定です。gitignoreに含めることで、個人的なデバッグ設定や通知の好みをチームに影響させずに管理できます。
4つ目はサブディレクトリ設定で、特定のディレクトリ配下にCLAUDE.mdを配置することで、そのディレクトリでの作業時にだけ追加の指示を適用できます。モノレポ（モノリポジトリ）でフロントエンド・バックエンドごとに異なるルールを設定する場合に有効です。
読み込み順は、ディレクトリツリーを上から下にたどる形で行われます。上位のCLAUDE.mdで定義された内容は、下位のCLAUDE.mdで上書き・補足できます。ただし、別のサブディレクトリの設定は互いに読み込まれません。他チームのCLAUDE.mdが意図せず読み込まれる場合は、claudeMdExcludes設定で除外できます。
関連記事：Claude Codeの使い方｜基本操作からスキル・CLAUDE.mdまで解説
書くべき内容と書くべきでない内容の判断基準
CLAUDE.mdの設計で最も重要な原則は、Anthropic公式が明示している「Claudeがコードを読んでも推測できないことだけを書く」というルールです。各行について「これを削除するとClaudeが間違いを犯すか？」と問いかけ、答えがNoであれば削除すべきです。
書くべき5つのカテゴリ
公式ドキュメントとコミュニティの実践から、CLAUDE.mdに書くべき内容は以下の5つに整理できます。
第1はビルド・テストコマンドです。「npm run build」「pytest tests/ -v」など、プロジェクトのビルドやテスト実行に使う具体的なコマンドを記載します。Claudeはpackage.jsonやMakefileを読めますが、特定のフラグや環境変数が必要な場合はCLAUDE.mdで明示しておくと確実です。
第2はコーディング規約のうち、リンターで強制できないものです。たとえば「エラーハンドリングでは空のcatchブロックを使わない」「APIレスポンスのDate型はISO 8601文字列で返す」など、コードの意図や設計方針に関わるルールが対象です。ESLintやPrettierで強制できるルール（インデント幅やセミコロンの有無など）は、ツール側で設定すべきでありCLAUDE.mdには書きません。
第3はプロジェクト固有のアーキテクチャ情報です。「認証ロジックはauth-service.tsが正しいエントリポイントで、auth.tsは直接編集しない」「環境変数の追加は.env.exampleにも反映する」など、コードベースの構造から読み取れない暗黙の設計ルールを明文化します。
第4は過去の事故から得た教訓です。「auth.tsを直接変更すると認証テストが全滅する（2025年10月の事故を参照）」のように、具体的な失敗事例とその回避策を記載しておくと、同じ過ちの再発を防げます。
第5はコミットメッセージの規約です。「feat:, fix:, chore:, docs:のプレフィックスを使い、本文は日本語で書く」など、Gitの運用ルールを指定します。Anthropic公式でも「リポジトリエチケット」としてCLAUDE.mdの推奨カテゴリに含まれています。
書くべきでない3つのアンチパターン
逆に、CLAUDE.mdに書くべきでない内容も明確に存在します。
1つ目のアンチパターンは「リンターやフォーマッターで強制できるルール」です。インデント幅、セミコロンの有無、改行スタイルなどは、ESLint・Prettier・gofmtなどのツール側で設定し、PostToolUseフックで自動実行する設計がベストプラクティスです。CLAUDE.mdに書いても、Claudeが100%守る保証はありません。
2つ目は「API仕様書やチュートリアルのような長文ドキュメント」です。CLAUDE.mdに200行を超えるドキュメントを詰め込むと、コンテキストウィンドウを圧迫し、他の指示の遵守率が低下します。Anthropic公式は「膨らんだCLAUDE.mdファイルはClaudeがあなたの実際の指示を無視するようにする」と警告しています。長文のドメイン知識はSkills機能で切り出し、必要時にオンデマンドで読み込ませる設計に切り替えましょう。
3つ目は「/initコマンドで自動生成した内容をそのまま使うこと」です。最新の研究では、AIが自動生成したCLAUDE.mdは何もない状態よりも精度が下がるという結果が報告されています。/initの出力はあくまでたたき台として活用し、プロジェクトの実情に合わせて手動で編集・精査することが推奨されます。自動生成された内容を鵜呑みにせず、各行の必要性を自分の目で判断する姿勢が、効果的なCLAUDE.mdを構築するための前提条件です。
関連記事：Claude Code × VSCode｜拡張機能の導入・使い方・CLI版との違いを解説
| Claude Codeの導入やCLAUDE.mdの最適化について、専門のコンサルタントが無料でご相談を承ります。自社プロジェクトに最適な設定を一緒に検討しませんか。 ▶ 無料相談フォームはこちら |
行数の目安と分割設計：200行ルールの実践
CLAUDE.mdの行数は、Claudeの出力品質に直接影響します。Anthropic公式ドキュメントでは「1ファイルあたり200行以内を目標にする」と明記されており、行数が多いほど個々の指示の遵守率が下がると指摘されています。
60行・200行・300行ルールの使い分け
行数に関しては3つの基準が存在しています。60行前後はHumanLayer社が提唱する「最適ライン」で、コンテキストウィンドウへの負荷を最小限に抑えつつ、必要十分なルールを網羅できる分量です。個人プロジェクトや小規模チームではこの水準を目指すのが現実的です。
200行はAnthropic公式の推奨上限で、中規模プロジェクトの目安です。これを超えると遵守率の低下が顕著になるため、200行を超えた時点で.claude/rules/への分割を検討すべきです。
300行はコミュニティ（HumanLayer社発）の事実上の上限ラインで、これを超えるCLAUDE.mdは「確実に分割が必要」とされています。300行以上のファイルは、Claudeが重要な指示を見落とすリスクが高まります。
@importと.claude/rules/による分割設計
ファイルが肥大化した場合の対策として、2つの分割手段が用意されています。
1つ目は@importディレクティブで、CLAUDE.md内に「@rules/code-style.md」のように記述することで、外部ファイルを読み込めます。ただし、@importは編集しやすさと整理のための機能であり、トークン消費自体は減りません。分割しても全ファイルがセッション開始時に読み込まれる点に注意が必要です。@importの階層深度は5階層までという制限があります。
2つ目は.claude/rules/ディレクトリで、配下のMarkdownファイルにYAMLフロントマターでpathsフィールドを指定すると、特定のファイルパターンに一致するときだけルールが読み込まれます。たとえば「paths: [‘src/api/**/*.ts’]」と指定すれば、APIディレクトリのファイルを編集するときだけルールが適用され、コンテキストの無駄遣いを防げます。
運用の推奨パターンとしては、CLAUDE.md本体は@importの目次だけにして薄く保ち、実際のルールは.claude/rules/配下に1トピック1ファイルで分割する設計です。各ファイルは60〜100行を目安にし、冒頭に「いつ適用されるか」「何を目的とするか」を明記しておくと、メンテナンス性が向上します。
分割のコツとして、ルールファイルの粒度が揺れないよう、メタルールを1つ設けておく方法があります。たとえば「1ファイル1トピック」「ファイル名はkebab-case（例：code-style.md、testing.md）」「新しいルール追加時は既存ファイルへの追記を優先し、100行を超えたら分割する」といったルールを定めておくと、チームメンバー間での運用のブレを防げます。
さらに、シンボリックリンクを活用すれば、複数プロジェクトで共通のルールファイルを共有することも可能です。社内のテンプレートリポジトリに標準ルール集を用意し、各プロジェクトの.claude/rules/からシンボリックリンクを張ることで、組織全体のコーディング標準を統一できます。
関連記事：Claude Code料金｜Pro・Max・API全プラン比較と失敗しない選び方
実務で効果のあるCLAUDE.md設定例
ここでは、現場で実際に効果が確認されている設定例をカテゴリ別に紹介します。すべての設定を一度に追加するのではなく、自社プロジェクトの課題に合ったものから段階的に導入してください。
ワークフロー制御：計画の事前提示
Anthropic公式のベストプラクティスでは、「いきなりコーディングに入る」ことが明確にアンチパターンとして挙げられています。CLAUDE.mdに「実装前に計画を提示し、承認を得てからコーディングを開始すること」と記載しておくことで、見当違いの方向に大量のコードを書かれてから手戻りが発生する事態を防げます。
具体的には「リサーチ→計画→実装→検証」のフェーズ分けを指示し、各フェーズの完了条件を明示するのが効果的です。計画段階でClaudeの方針を確認し、軌道修正できることで、開発効率が大きく向上します。
ワークフローの指示に加えて、「変更を加える前に既存のテストを実行して現状を確認する」という指示も有効です。既存のテストが通っている状態を確認してから変更に着手することで、自分が壊した部分を明確にでき、デバッグ効率が大幅に向上します。この「まず現状確認、次に変更」というパターンは、Claude Codeの公式ベストプラクティスでも繰り返し推奨されています。
エラーハンドリングとセキュリティの指示
Claudeはタスクを素早く完了しようとする傾向があり、その過程でエラーハンドリングが甘くなることがよく報告されています。空のcatchブロックやconsole.error(e)だけで済ませるパターンは頻繁に発生するため、「エラーは適切にログ出力し、ユーザーに意味のあるメッセージを返すこと」という指示をCLAUDE.mdに含めておくと品質が安定します。
セキュリティ面では、「.envファイルにシークレット情報をハードコードしない」「外部入力は必ずバリデーションする」「SQLインジェクション対策としてプレースホルダーを使う」といった基本的なセキュリティルールも効果的です。これらはプロジェクトの種類によらず普遍的に適用できる内容です。
テスト方針とコミットメッセージの規約
テストに関するルールもCLAUDE.mdに含めるべき重要な項目です。「新しい関数を追加したら対応するユニットテストも必ず書くこと」「テストファイルは__tests__ディレクトリに配置すること」「テスト名はit(‘should 〜’)の形式で書くこと」など、テストの構造と命名規則を明記しておくと、Claudeが生成するテストコードの品質が大幅に向上します。
コミットメッセージの規約も、チーム開発では重要な設定項目です。プレフィックス（feat:, fix:, chore:, docs:）を英語のまま使い、本文は日本語で書くというルールにすると、git logの視認性と日本語チームでの扱いやすさを両立できます。Claudeは指示がなければ英語でコミットメッセージを書く傾向があるため、「コミットメッセージは日本語で書くこと」と明記しておくことが推奨されます。
参考：Anthropic公式「Claude Codeのベストプラクティス」
| AIエージェントの導入事例や、PoCから本番化までの進め方をまとめた資料を無料でダウンロードいただけます。Claude Codeの活用を検討されている方は、ぜひご覧ください。 ▶ 資料請求フォームはこちら |
チーム運用と定期メンテナンスのコツ
CLAUDE.mdを個人利用から卒業してチームに展開する際には、管理方法と運用ルールの整備が重要です。個人のCLAUDE.mdは「自分さえわかればいい」で済みますが、チーム共有のCLAUDE.mdには再現性と保守性が求められます。
Git管理と変更履歴の運用
チーム共有のCLAUDE.md（プロジェクトルートの.claude/settings.json配下）は、README.mdと同じようにGitで管理するのが基本です。変更時には「なぜ追加したか」をコミットメッセージに記載し、変更の背景を後から追跡できるようにします。
個人設定はCLAUDE.local.mdに記述し、.gitignoreに含めることでチーム設定との競合を防ぎます。新メンバーのオンボーディング資料にCLAUDE.mdの場所と役割を記載しておけば、プロジェクトへの参加と同時にClaude Codeの設定が自動適用される仕組みが構築できます。
モノレポ（モノリポジトリ）環境では、ルートのCLAUDE.mdに全体方針と共通規約を置き、各パッケージディレクトリ（frontend/、backend/など）にパッケージ固有のCLAUDE.mdを配置する階層構成が効果的です。フロントエンドチームのReact規約とバックエンドチームのAPI設計規約を分離できるため、チーム間の設定衝突を防ぎつつ、共通ルールは上位ファイルで一元管理できます。
インフラのコード（Terraform、Kubernetes YAML、デプロイスクリプトなど）を扱うディレクトリのCLAUDE.mdには、破壊的操作への明示的なガードを設けることが特に重要です。「terraform applyは実行しない」「本番環境のkubectlコマンドは実行しない」といった禁止事項を明記し、Hooksと併用して確実にブロックする二重防御の設計が推奨されます。
月1回の定期レビューとSkillsとの使い分け
CLAUDE.mdは静的なドキュメントではなく、「育てて剪定するコード」として扱うべきです。Anthropic公式では「3〜6ヶ月ごとの見直し」を推奨しており、月1回のスプリント振り返り時にCLAUDE.mdのレビューを組み込むのが実践的です。
レビュー時のチェックポイントは3つです。まず「追加してから一度もClaudeの動作に影響しなかった行はないか」を確認し、不要な行を削除します。次に「新しいモデルバージョンで不要になった指示はないか」を検証します。モデルの進化により、以前は必要だった指示が不要になるケースは珍しくありません。最後に「Skills機能に切り出すべきドメイン知識が混在していないか」を確認し、セッション開始時のコンテキスト負荷を最適化します。
Skillsは「必要なときだけオンデマンドで読み込まれる知識パッケージ」であり、CLAUDE.mdの「毎セッション自動読み込み」とは対照的な設計です。ドメイン固有の詳細な知識や、ときどきしか使わないワークフローは、CLAUDE.mdではなくSkillsに切り出すことで、コンテキストウィンドウの効率的な活用が実現します。
CLAUDE.mdとSkills、そしてHooksの使い分けを整理すると、CLAUDE.mdは「Claudeに毎回覚えておいてほしい前提条件」、Skillsは「必要時に参照する専門知識」、Hooksは「確実に実行したい処理（ツール強制）」という役割分担になります。この3つを適切に使い分けることが、Claude Codeの運用品質を最大化する鍵です。
具体的な使い分けの例として、コーディング規約のうち「型定義にはinterfaceではなくtypeを使う」という好みはCLAUDE.mdに書きますが、「編集後のPrettierフォーマット実行」はHooksのPostToolUseで自動化し、「特定のAPIライブラリの使い方マニュアル」はSkillsに切り出すのが適切です。CLAUDE.mdに全部詰め込むのではなく、性質に応じて適切な場所に配置することで、コンテキストウィンドウの効率化と指示の遵守率向上を同時に実現できます。
なお、CLAUDE.mdの運用においては、新しいモデルがリリースされたタイミングでの見直しも重要です。Anthropic公式も「以前のモデル向けに最適化された指示は、新しいモデルでは不要なオーバーヘッドになる可能性がある」と明記しています。モデルの進化に合わせてCLAUDE.mdを「剪定」していく姿勢が、長期的な運用の質を左右します。
関連記事：Claude Code Windows｜3つのインストール方法・エラー対処・活用術を解説
関連記事：OpenAI Codexとは？使い方・料金・Claude Codeとの違いを解説
| Claude Codeの導入やCLAUDE.mdの最適化について、専門のコンサルタントが無料でご相談を承ります。自社プロジェクトに最適な設定を一緒に検討しませんか。 ▶ 無料相談フォームはこちら |
まとめ
CLAUDE.mdは、Claude Codeの動作を安定させ、開発チームの生産性を向上させるための重要な設定ファイルです。ただし、その効果を最大化するには「少なく書く」ことが最も重要なベストプラクティスであり、行数を増やすほど各指示の効果が薄れるという特性を理解する必要があります。言い換えれば、CLAUDE.mdの品質は「何を書いたか」ではなく「何を書かなかったか」で決まるのです。
本記事では、CLAUDE.mdの役割と4つの配置階層、書くべき5つのカテゴリと3つのアンチパターン、60行・200行・300行の行数基準、@importと.claude/rules/による分割設計、ワークフロー制御やエラーハンドリングの実践的な設定例、そしてチーム運用でのGit管理と月1回の定期レビューの方法を、Anthropic公式ドキュメントとコミュニティの知見をもとに解説しました。
まず取り組むべきは、現在のCLAUDE.mdの行数を確認し、200行を超えている場合は.claude/rules/への分割を検討することです。各行に対して「これがないとClaudeがミスをするか？」を問いかけ、不要な行を剪定するだけでも、Claudeの出力品質は目に見えて改善します。
チーム開発においては、CLAUDE.mdをREADME.mdと同じようにGitで管理し、変更の意図をコミットメッセージに記録する運用を導入してください。月1回のスプリント振り返りでCLAUDE.mdのレビューを組み込むことで、陳腐化を防ぎ、常に最新の開発環境に最適化された状態を維持できます。CLAUDE.mdは一度書いて終わりではなく、プロジェクトとともに育てていく継続的な取り組みとして位置づけましょう。
