CLAUDE.md 公式＆最新ベストプラクティスまとめ (2026年版)

はじめに

プロンプトをいくら調整しても、AIが期待通りに動かないことはありませんか？

指示を細かく書けば書くほど、AIは別の重要なルールを忘れ、つぎはぎのコードを提案してくる。
場当たり的なプロンプトの修正は、一時的に動くコードを生むかもしれませんが、それはコンテキストを汚染し、やがてAIがプロジェクトの全体像を見失う原因となります。

この記事をお勧めしない人

AIに「使い捨てのコード」だけを書かせれば十分だと考えている人。
プロンプトを「呪文」として捉え、その背後にあるコンテキストの構造に興味がない人。
10年続く大規模なプロジェクトを、AIと共に維持していく覚悟がない人。

肥大化した指示が招く「認知の麻痺」

CLAUDE.md に情報を詰め込みすぎると、AIは重要な指示を無視する「簡潔さバイアス」に陥る。
指示同士が競合し、AIは「何が正解か」を判断できなくなり、開発の勢いが確実に削ぎ落とされていく。
最終的に、コンテキストの汚染が限界を迎え、AIは「昨日までできていたこと」すらできなくなるブラックボックスへと化す。

Context Engineering という明るい未来

この記事を読めば、プロンプトを「指示」から「設計図」へと昇華させ、AIが迷いなく自走する明るい未来があります。
具体的には、AIの認知リソースを最適化し、必要な情報を必要な時だけ提供する「段階的開示」の手法を習得できます。
この方法は、筆者が運営する「ClaudeMix」において、大規模なリファクタリングをAIと共に完遂した過程で実証済みです。
この情報は、単なるテクニックを超えた、AI時代のシステム設計における「最強の地図」に関する、巷では得られない知見です。

このブログもそうでした

筆者も初期は数千行の CLAUDE.md に苦しみ、AIがルールを無視し続ける「コンテキストの地獄」を経験しました。
この記事で、AIに「思想」を継承させ、最小限の指示で最大限の成果を引き出すための、明日から使えるTipsを凝縮しました。
AIとの共生を真剣に考える方は、最新のベストプラクティスを確認できます。

開発の進捗

Before: プロンプトを試行錯誤で都度入力し、AIの出力が安定せず、コンテキストの肥大化に悩まされていた。
Current: CLAUDE.md を中心とした「Context Engineering」への転換が進み、AIがプロジェクトの構造を自律的に把握できるようになった。
Next: RulesやSkillsとの連携をさらに深め、AIが「迷わず、迷わせず」自走できる究極の開発環境を構築する。

具体的なタスク

Before: 大量の指示を CLAUDE.md に詰め込み、重要なルールが無視される現象が発生していた。
Current: WHAT/WHY/HOWの3要素に情報を凝縮し、詳細を外部ファイルへ委譲する「段階的開示」を適用。
Next: プロジェクト固有の rules/ と skills/ を整備し、AIの認知リソースを最も重要な「設計判断」に集中させる。

概念の転換：Prompt から Context Engineering へ

2026年現在、CLAUDE.md は単なる指示書ではなく、AIのための情報ペイロード（情報資産）の設計図と定義されます。LLMはステートレス（状態を持たない）であるため、セッションごとに適切な「地図」を渡す必要があります。

黄金の3要素（WHY / WHAT / HOW）

最新のベストプラクティスでは、以下の3点に絞った記述が推奨されます。

WHAT（地図） : 技術スタック、プロジェクト構造。Claudeが迷子にならないための全体像。
WHY（思想） : プロジェクトの目的、設計意図。なぜこの構成なのかという「背景」を理解させ、適切な判断を促す。
HOW（検証） : 作業手順ではなく「変更の是非をどう判断するか」。テスト、型チェック、ビルド方法など。

2. CLAUDE.md の最適化原則

「少ないほど良い」の徹底

300行未満（理想は60〜100行） : 情報が多すぎると、重要な指示ほど無視される「Brevity Bias（簡潔さバイアス）」や「指示の均一な無視」が発生します。
指示ではなく「事実」を書く : 「〜せよ」という命令よりも、「〜という設計方針である」という事実形式の方が、AIの推論に組み込まれやすくなります。
リンターの仕事をさせない : コードスタイル（インデント等）は自動ツールに任せ、CLAUDE.md には書かないのが鉄則です。

段階的開示（Progressive Disclosure）

すべてのルールを1つのファイルに詰め込まず、ポインタ（参照）を活用します。

タスク固有の指示 : agent_docs/ 等の別ファイルに分離する。
コピーより参照 : コードスニペットを直接貼らず、file:line 形式でソースコード自体を参照させる。

3. 構造化されたルール管理（.claude/rules/）

新機能として、ディレクトリベースのルール管理が導入されました。

機能	内容
自動読み込み	`.claude/rules/` 内の `.md` は `CLAUDE.md` と同等の優先度で読み込まれる。
パス固有のルール	YAMLフロントマターの `paths` で、特定のファイル操作時のみルールを適用可能（例: `src/components/*.tsx`）。
ノイズ削減	タスクに関係ないルールを読み込ませないことで、AIの「注意力」を温存する。

4. サブエージェントとスキルの使い分け

AIの「認知リソース（スタミナ）」を管理するための戦略的運用です。

スキル (Skills): プロジェクト共通の「武器（ツール）」。標準化された手順やAPI操作。
サブエージェント (Sub-agents): 独立した「作業員」。メインの会話（コンテキスト）を汚さずに、重いタスクや調査を別ウィンドウで完結させる。
運用の肝 : メインエージェントが持つ「思想（CLAUDE.md）」をサブエージェントに継承させ、汚れ仕事だけを任せる。

5. 推奨ワークフロー：Explore-Plan-Code-Commit

公式が推奨する、ミスを最小限にするための4ステップです。

Explore: 関連ファイルを読み込む。「コードはまだ書かない」と指示。
Plan: 実装計画を立てさせ、ユーザーが承認する。
Code: 計画に基づき実装。
Commit: 変更を確認し、コミット。

このガイドの内容を実際のプロジェクトでどう運用したかは、CLAUDE.mdを公式ベストプラクティスで全面リファクタリングした実践記録でコードと共に確認できます。WHAT/WHY/HOWへの再構築と情報のポインタ化を経て、約1,600トークンのコンテキスト削減を実現した過程です。

ソース :

[1] Anthropic公式: https://www.anthropic.com/engineering/claude-code-best-practices

[2] izanami.dev: CLAUDE.md や AGENTS.md のベストプラクティスな書き方