プロジェクトの「記憶」を設計する基本
CLAUDE.mdは、Claude Codeがセッション開始時に自動で読み込む「永続的な指示書」です。 プロジェクトのルール、技術仕様、禁止事項などを書いておくと、 毎回のセッションでClaude Codeがその内容を前提として動作します。
通常のプロンプト（対話画面での指示）は、セッションが変わるとリセットされます。 一方、CLAUDE.mdに書いた内容は、誰がいつセッションを開始しても必ず読み込まれます。 つまり、チーム全員で共有できる「AIへの業務マニュアル」のようなものです。
プロンプトとの違い: プロンプトは「その場限りの指示」、CLAUDE.mdは「常に適用されるルール」です。 毎回同じことを指示しているなら、それはCLAUDE.mdに書くべきサインです。
CLAUDE.mdの読み込みには2つのメカニズムがあります。 この仕組みを理解しておくと、ファイルの配置場所を正しく選べるようになります。
Claude Codeを起動したディレクトリから、上の階層に向かってCLAUDE.mdを探します。 見つかったものはすべて即座に読み込まれます。 たとえば/project/src/で起動した場合、/project/src/CLAUDE.mdと/project/CLAUDE.mdの両方が読み込まれます。
起動ディレクトリより下の階層にあるCLAUDE.mdは、 そのディレクトリ内のファイルに実際にアクセスしたタイミングで読み込まれます。 起動時には読み込まれないため、不要なコンテキスト消費を防げます。
注意: 兄弟ディレクトリのCLAUDE.mdは読み込まれません。 たとえばfrontend/ディレクトリで作業しているとき、backend/CLAUDE.mdは読み込まれません。 モノレポ（複数プロジェクトが1つのリポジトリにある構成）では、 この仕様を意識してCLAUDE.mdを配置する必要があります。
CLAUDE.mdは目的に応じて4つの場所に配置できます。 それぞれ読み込まれるスコープが異なります。
~/.claude/CLAUDE.mdすべてのプロジェクトで共通して適用したいルールを書きます。 たとえば「応答は常に日本語で」「コミットメッセージのフォーマット」など、 自分の作業スタイルに関わる設定です。
# グローバル設定（~/.claude/CLAUDE.md）
- 応答は日本語で行うこと
- コードにはコメントを日本語で追加すること
- ファイルを削除する前に必ず確認すること./CLAUDE.mdそのプロジェクト固有のルールや技術情報を書きます。 チームで共有するため、Gitリポジトリにコミットします。 最も重要で、最も頻繁に使う配置場所です。
./src/CLAUDE.md特定のディレクトリに固有のルールがある場合に使います。 たとえばsrc/components/ディレクトリに 「コンポーネントの命名規則」を置くといった使い方です。
CLAUDE.local.md自分だけの設定を書くファイルです。.gitignoreに追加して、チームには共有しません。 個人的な作業環境の設定や、自分用のショートカット指示などに使います。
CLAUDE.mdに何を書けばよいか迷ったら、まず以下の5項目から始めてください。
このプロジェクトが何なのかを1〜2文で説明します。 Claude Codeが作業の文脈を正しく理解するための土台になります。
使用しているフレームワーク、言語、主要なライブラリを列挙します。
命名規則、ファイル構成のルール、コメントの書き方など。 既存のコードと一貫性のある出力を得るために重要です。
「やってはいけないこと」を明記します。 たとえば「本番データベースに直接アクセスしない」 「.envファイルの内容をコードに直書きしない」などです。
テストの実行コマンド、デプロイの手順を書いておくと、 Claude Codeが自動でテストを実行したり、 デプロイ前のチェックを行ったりできるようになります。
# プロジェクト概要
飲食店向けの予約管理Webアプリケーション。
# 技術スタック
- Next.js 15 (App Router)
- TypeScript
- Supabase (データベース・認証)
- Tailwind CSS
# コーディング規約
- コンポーネントはPascalCase（例: ReservationCard）
- 関数はcamelCase（例: formatDateTime）
- コメントは日本語で記述
# 禁止事項
- .envファイルの内容をハードコードしない
- any型を使わない
- console.logを本番コードに残さない
# テスト・デプロイ
- テスト実行: npm run test
- ビルド確認: npm run build
- デプロイ前に必ずビルドが通ることを確認するCLAUDE.mdは便利ですが、書きすぎると逆効果になります。 Claude Codeの開発に携わるBoris Cherny氏は、200行以下に収めることを推奨しています。
CLAUDE.mdの内容はセッション開始時にコンテキストウィンドウに読み込まれます。 ここに大量の情報を詰め込むと、実際の作業に使えるコンテキストが減り、 指示の優先順位もあいまいになって精度が下がります。
また、Claude CodeにはAuto Memory機能があり、 作業中に学んだ情報を自動的にCLAUDE.mdに追記することがあります。 定期的にファイルを見直して、不要な記述を整理する習慣をつけてください。
目安: CLAUDE.mdは「新しく入ったチームメンバーに最初に伝える情報」と同じ粒度が適切です。 細かい手順書ではなく、判断の指針となるルールを書いてください。
チームで作業する場合、個人の好みや環境に依存する設定はCLAUDE.local.mdに分離します。 このファイルは.gitignoreに追加して、リポジトリには含めません。
# .gitignore に追加
CLAUDE.local.mdCLAUDE.local.mdには、たとえば以下のような内容を書きます。
# 個人設定（CLAUDE.local.md）
- 私の名前は田嶋です。コミットメッセージに名前を含めてください
- ローカルの開発サーバーはポート3001で起動しています
- テスト実行時は --watch オプションをつけてくださいこのように、プロジェクト共通のルールはCLAUDE.mdに、 個人の環境設定はCLAUDE.local.mdに分けることで、 チーム全体の生産性と個人の作業効率を両立できます。