CLAUDE.md 完全ガイド｜Claude Codeにプロジェクト指示を書く方法【初学者向け】

CLAUDE.md は、Claude Code をプロジェクトで使う上で最も重要なファイルです。本記事では、その役割・配置場所・/init での自動生成・効果的な書き方の4原則・実用テンプレートまでを、初学者向けに体系的に解説します。

📌 CLAUDE.md とは何か（ひとことで）

CLAUDE.md とは、Claude Code が毎セッションの開始時に必ず読み込む「プロジェクト用の指示書ファイル」です。

プロジェクトのコーディング規約（コードを書くときのルール）・ビルドコマンド（プログラムを動かす形に組み立てる命令）・アーキテクチャ方針（プログラム全体の設計の考え方）などを書いておくと、Claude が毎回その内容を踏まえて作業してくれます。普通の Markdown（マークダウン：見出しや箇条書きを # や - で表す軽量な文書形式。.md 拡張子）ファイルなので、難しい記法は不要です。

---

💡 なぜ CLAUDE.md が「最重要」なのか

Claude Code のセッションは、毎回まっさらな状態から始まります。前のセッションで「このプロジェクトは TypeScript（マイクロソフトが開発した、型チェック付き JavaScript の上位言語）を使う」「テストは npm test（Node.js のパッケージ管理ツール npm から、設定済みのテストコマンドを呼び出す命令）で走る」「API ハンドラ（リクエストを受けて返す処理を書く関数）は src/api/ に置く」と教えても、次のセッションでは Claude は何も覚えていません。

そこで CLAUDE.md の出番です。このファイルに書いた内容は、Claude が毎回最初に読み込みます。一度書いておくだけで、毎回同じ説明を繰り返す手間が省け、Claude の作業精度が大幅に向上します。

---

🏠 STEP 1：CLAUDE.md の配置場所

CLAUDE.md はいくつかの場所に置けますが、初学者がまず覚えるべきなのは2つだけです。

基本：プロジェクトのルートに置く

プロジェクトフォルダの直下に ./CLAUDE.md（先頭の ./ は「現在いるフォルダ」を表す書き方）を置きます。これがチーム全員と共有される、プロジェクト共通のルールになります。Git（ファイル変更履歴を記録するバージョン管理ツール）で管理して、メンバー全員が同じルールで作業できる状態にするのが基本です。

応用：自分専用の設定は別ファイル

そのプロジェクトでの「自分だけの好み」は、./CLAUDE.local.md に書きます。これは .gitignore（ジットイグノア：Git に含めたくないファイル名のリストを書く設定ファイル）に追加して Git に含めないことで、ローカル環境（自分のパソコン）専用の設定として扱えます。

配置場所の早見表

場所	役割	共有範囲
./CLAUDE.md	プロジェクト共通（最重要）	チーム全員（Git経由）
./.claude/CLAUDE.md	上と同じ役割（こちらでも可）	チーム全員
./CLAUDE.local.md	プロジェクトでの自分専用	自分のローカル環境のみ
~/.claude/CLAUDE.md	全プロジェクト共通の自分のルール	自分の全プロジェクト

これらはすべて読み込まれて連結される仕組みになっており、より具体的な場所のルールが優先されます。

---

⚡ STEP 2：いきなり書かず、まず /init で初版を自動生成

ゼロから書こうとすると手が止まってしまうので、まずは Claude 自身に初版を書かせるのが正解です。

プロジェクトフォルダで claude を起動し、対話プロンプトに以下を入力します。

/init

すると Claude があなたのコードベースを自動で読み込み、ビルドコマンド・テストコマンド・プロジェクト構成・依存関係などを発見して、初版の CLAUDE.md を作成してくれます。すでに CLAUDE.md がある場合は、上書きせず改善案を提案してくれる仕様です。

生成された内容を確認しながら、足りない部分（後述の「やってほしくないこと」など）を手で書き足していくのが、もっとも効率的なフローです。

---

✍️ STEP 3：効果的な書き方の4原則

CLAUDE.md は「書けば書くほど良い」というものではありません。以下の4つの原則を守ることで、Claude が指示を確実に守ってくれる、質の高い CLAUDE.md になります。

原則1：サイズは200行以内に収める

CLAUDE.md は毎回コンテキストウィンドウ（AI が一度に読める情報量の上限。「短期記憶の容量」のようなもの）に読み込まれるため、長すぎると Claude の集中力が散らばり、かえって指示が守られにくくなります。200行を目安に簡潔に保つのが鉄則です。

長くなりそうな場合は、後述する .claude/rules/ でルールを分割するか、@ でファイルをインポートする方法を使ってください。

原則2：曖昧ではなく具体的に書く

これがもっとも重要な原則です。「人間でも判断に迷う指示」は、Claude にとっても判断できません。検証できるレベルまで具体化してください。

❌ 悪い例（曖昧）	✅ 良い例（具体的）
コードを綺麗に書いて	インデントは2スペース、セミコロンは付けない
テストを忘れずに	コミット前に npm test を必ず実行する
ファイルは整理して	API ハンドラは src/api/handlers/ に置く
セキュリティに気をつけて	ユーザー入力は必ず zod.parse() でバリデーションする

原則3：マークダウンで構造化する

見出しと箇条書きで整理しましょう。Claude も人間と同じで、構造化された文書のほうが読み取りやすく、指示を正確に解釈できます。だらだら書いた長文よりも、見出し + 箇条書きの方がはるかに効果的です。

原則4：定期的に見直して矛盾を排除する

使い続けているうちに、矛盾するルールが混ざってしまうことがあります。例えば「Tailwind CSS（クラス名でデザインを当てるユーティリティ系 CSS フレームワーク）を使う」と書きつつ「styled-components（JS の中に CSS を書くスタイル管理ライブラリ）を使う」と矛盾するルールが両方残っていると、Claude はどちらか一方を適当に選んでしまいます。

月1回程度、CLAUDE.md を読み返して整理する習慣をつけると、品質が保たれます。

---

📄 STEP 4：実用テンプレート（コピペで使えます）

下記は、Web アプリ開発を想定した実用的なテンプレートです。Next.js（React ベースの Web アプリ開発フレームワーク。Vercel 社製）／Prisma（プリズマ：データベース操作を型安全に書けるツール）／App Router（Next.js 13 以降のページ構成方式）といったツール名が出てきますが、すべて「Web 開発で広く使われているツール群」だと思って読んでください。これをベースに、自分のプロジェクトに合わせて調整してください。

# プロジェクト概要

このプロジェクトは、Next.js 14 + TypeScript + Prisma で構築された
社内向けタスク管理ツール「TaskFlow」です。

# よく使うコマンド

- 開発サーバー起動: `npm run dev`
- テスト実行: `npm test`
- Lint: `npm run lint`
- 本番ビルド: `npm run build`
- DB マイグレーション: `npx prisma migrate dev`

# プロジェクト構成

- `src/app/` … Next.js App Router のページ
- `src/components/` … React コンポーネント
- `src/lib/` … 共通ユーティリティ
- `src/server/api/` … API ハンドラ
- `prisma/schema.prisma` … DB スキーマ

# コーディングルール

- インデントは2スペース
- セミコロンは付けない
- コンポーネントは関数コンポーネント + TypeScript で書く
- Tailwind CSS を使う。styled-components や CSS Modules は使わない
- API 通信は `src/lib/api-client.ts` を経由する。直接 `fetch` を呼ばない

# やってほしいこと / やってほしくないこと

- ✅ 新しい機能を追加するときは、必ずテストも一緒に書く
- ✅ DB スキーマを変更したら、必ずマイグレーションファイルも生成する
- ❌ `src/legacy/` の中のファイルは触らない（移行中のレガシーコード）
- ❌ パッケージを追加する前に、必ず確認を取る

ポイントは「やってほしいこと」と「やってほしくないこと」を明示的に書き分けることです。とくに「触ってはいけないファイル」を書いておくと、思わぬ事故を防げます。

---

🔗 STEP 5：応用テクニック（慣れてきたら）

基本の CLAUDE.md に慣れたら、以下の応用テクニックでさらに整理できます。最初から覚える必要はありません。

A. 別ファイルをインポートする @ 記法

CLAUDE.md の中で、別のファイルを取り込めます。

プロジェクト概要は @README.md を参照。
利用可能な npm コマンドは @package.json を見ること。

# 追加ルール
- Git ワークフローについては @docs/git-workflow.md

これにより、すでに存在する README やドキュメントを再利用でき、CLAUDE.md 本体を簡潔に保てます。

B. サブディレクトリにも配置できる

大きなプロジェクトでは、src/api/CLAUDE.md のようにサブフォルダにも配置できます。Claude がそのフォルダ内のファイルを読むときだけ、その CLAUDE.md が追加で読み込まれる仕組みです。

「APIだけのルール」「フロントエンドだけのルール」のように、コンポーネント単位でルールを分けたいときに有効です。

C. .claude/rules/ でルールを分割する

さらに大規模なプロジェクトでは、.claude/rules/ ディレクトリにテーマごとのルールファイルを配置できます。

.claude/
└── rules/
    ├── code-style.md      # コード規約
    ├── testing.md         # テスト方針
    ├── api-design.md      # API設計
    └── security.md        # セキュリティ要件

各ファイルに YAML フロントマター（ヤムル：構造化データ形式の YAML を、Markdown ファイルの先頭に --- で囲んで埋め込んだメタデータ部分）で対象パスを指定すれば、特定のファイルを編集するときだけ適用されるルールにできます。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール

- すべての API エンドポイントは入力バリデーションを必須とする
- エラーレスポンスは標準フォーマットに従う
- OpenAPI ドキュメントコメントを含める

こうすることで、Claude は src/api/ 配下のファイルを編集するときだけ、このルールを適用するようになります。

---

🤖 STEP 6：Auto Memory との使い分け

CLAUDE.md とは別に、Claude Code には Auto Memory という機能があります。これは混同しやすいため、明確に違いを理解しておきましょう。

	CLAUDE.md	Auto Memory
誰が書く	あなた	Claude 自身
内容	ルール・規約	学習・気づき
共有範囲	チーム全員（Git経由）	自分のマシンのみ
用途例	「インデントは2スペース」	「テストは npm run test:unit で動く」

セッション中に「これ覚えておいて」と Claude に頼むと Auto Memory に保存されます。一方、「これを CLAUDE.md に追加して」と頼めば CLAUDE.md に書き込まれます。この使い分けを意識すると、それぞれの強みを活かせます。

保存されている内容は、/memory コマンドで一覧・編集できます。

---

⚠️ よくある失敗パターン

失敗1：Claude が指示を守ってくれない

まずは /memory コマンドを実行し、CLAUDE.md が実際に読み込まれているか確認してください。読み込まれているのに守られない場合は、たいてい以下のどちらかが原因です。

• 指示が抽象的すぎる（「綺麗に書く」のような具体性のない指示）
• 他のルールと矛盾している（前述のとおり）

失敗2：CLAUDE.md が肥大化してしまった

200行を超えたら分割を検討してください。.claude/rules/ で対象ファイルごとに分けるか、@import で外部ファイルに切り出すと、本体を簡潔に保てます。

失敗3：個人情報・機密情報を書いてしまった

これは特に注意が必要です。API キー（外部サービスを呼び出すための鍵となる文字列。漏れると不正利用される）・サンドボックス用 URL（テスト環境のアドレス）・社内専用 URL などの機密情報は CLAUDE.md には絶対に書かないでください。CLAUDE.md は Git で共有される前提のファイルです。

これらの情報は CLAUDE.local.md に書き、必ず .gitignore に追加してください。

---

🎯 今日からできるアクションプラン

以下の手順で進めれば、効果的な CLAUDE.md がすぐに使える状態になります。

1. プロジェクトフォルダで claude を起動
2. /init コマンドを実行して初版を生成
3. 生成された CLAUDE.md を cat CLAUDE.md や VS Code で確認
4. 「コーディングルール」と「やってほしくないこと」のセクションを自分で追記
5. Claude Code を一度終了し、再起動
6. 「このプロジェクトのルールは何？」と質問して、設定通り答えるか確認

うまく答えてくれれば、CLAUDE.md が正しく機能している証拠です。

📘 公式ドキュメント：How Claude remembers your project (CLAUDE.md & Memory)

---

🎮 Claude Code 解説シリーズ・全記事一覧

シリーズの他の記事もどうぞぉ……気になるところから読んでねぇ。

📘 01. Claude Code 用語集（初学者向け・全23語）
🚀 02. インストールと初回起動ガイド
📝 03. CLAUDE.md 完全ガイド
🛠️ 04. 実践ワークフロー集
🛡️ 05. パーミッションと安全設定ガイド
⚡ 06. スラッシュコマンド & スキル完全ガイド
🔌 07. MCP・Hooks活用ガイド
🎭 08. サブエージェント・並列作業ガイド
🏆 09. プロのベストプラクティス完全集
🎨 10. Claude Code × 3DCG活用ガイド
🧊 11. Claude Code × Blender 導入ガイド