はじめに
CLAUDE.mdは、Claude Codeにプロジェクト固有の知識を教えるための「プロジェクトメモリファイル」です。このファイルを適切に設定すると、Claude Codeがあなたのプロジェクトの構造やルールを理解し、より的確な提案ができるようになります。
本記事は、Claude Codeの機能を体系的に解説する連載シリーズの第2回です。「CLAUDE.mdを作成して、プロジェクトに最適化されたClaude Code環境を構築する」 ことをゴールとしています。
対象読者
- Claude Codeをインストール済みの方（第1回完了前提）
- CLAUDE.mdの存在は知っているが使い方がわからない方
- 自分のプロジェクトに最適化したい方
連載予定
- #1: インストールから"使える"初期設定まで
- #2: CLAUDE.mdの書き方と育て方 （本記事）
- #3: パーミッション＆Sandbox完全ガイド
- #4: Hooks実践テクニック
- #5: Skills入門
- #6: MCP活用術
CLAUDE.mdの役割と効果
プロジェクト固有の記憶ファイル
CLAUDE.mdは、Claude Codeにおけるプロジェクトメモリファイルです。AIエージェントが自律的に実装を行う際に、プロジェクト固有の情報やルールを参照するための設定ファイルとして機能します。
設定前の状態
- 毎回プロジェクト構造を説明する必要がある
- コーディング規約を繰り返し指摘する必要がある
- Claude Codeが一般的な実装パターンを提案してしまう
設定後の状態
- セッション開始時に自動的にプロジェクト情報が読み込まれる
- プロジェクト固有のルールに従った提案がされる
- 「AIのためのユーザーマニュアル」として機能する
セッション間での指示永続化
CLAUDE.mdに書いた内容は、すべてのセッションで自動的に読み込まれます。一度書けば、毎回説明する必要がなくなります。
例: プロジェクトでTypeScript strictモードを使っている場合
CLAUDE.mdなし
あなた: 「この関数にany型が使われているので修正してください」
Claude: 「修正しました」
（次のセッション）
あなた: 「また any型が使われていますよ...」
CLAUDE.mdあり
# コーディング規約
- TypeScript strictモードを使用
- implicit anyは禁止（本番バグの原因になったため）
これだけで、Claude Codeは最初から型安全なコードを提案するようになります。
最速で始める: /initコマンド
/initの実行方法
新規プロジェクトでCLAUDE.mdを作成する際は、/initコマンドを使用するのが最速です。
cd your-project
claude
Claude Code起動後、プロンプトに以下を入力します。
/init
Claudeがプロジェクト構造を自動的に分析し、適切な初期設定を提案してくれます。
自動生成される内容
/initコマンドは以下の情報を自動的に検出して記述します。
| 検出項目 | 内容例 |
|---|---|
| プロジェクトタイプ | React, Next.js, Node.js, Python等 |
| ディレクトリ構成 | src/, components/, pages/等 |
| 技術スタック | TypeScript, Tailwind CSS, Jest等 |
| ビルドツール | package.jsonから検出 |
Tips: 生成されたCLAUDE.mdをそのまま使わず、プロジェクト固有の「変わった部分」を追記してください。一般的な情報（「componentsフォルダにコンポーネントを置く」等）は不要です。Claudeはすでに知っています。
CLAUDE.mdに書くべき内容
効果的なCLAUDE.mdは、WHAT（何）、WHY（なぜ）、HOW（どうやって） の3つの視点で構成します。
WHAT: プロジェクト構造
プロジェクトの全体像を伝えます。
含めるべき内容
- ディレクトリ構成と各ディレクトリの役割
- 主要ファイルの説明
- 技術スタック
例
## ディレクトリ構成
| ディレクトリ | 役割 |
|-------------|------|
| src/components/ | Reactコンポーネント（Atomic Design） |
| src/hooks/ | カスタムフック |
| src/api/ | API呼び出しロジック |
| src/types/ | TypeScript型定義 |
WHY: 設計原則と決定事項
プロジェクトの設計思想や、なぜそうしているのかを伝えます。
含めるべき内容
- アーキテクチャ方針
- 設計パターン
- 技術的な決定とその理由
例
## 設計原則
- TypeScript strictモード: 本番バグがimplicit anyから発生したため厳格化
- Atomic Design: コンポーネントの再利用性を高めるため
- Custom Hooks: ビジネスロジックとUIを分離
Tips: 理由を書くことで、予期しない判断場面でもClaudeが適切に対応できます。「何」だけでなく「なぜ」を伝えることが重要です。
HOW: コマンド集
頻繁に使うコマンドを記述します。
含めるべき内容
- ビルドコマンド
- テスト実行方法
- リントコマンド
- デプロイ手順
例
## よく使うコマンド
| コマンド | 説明 |
|---------|------|
| `npm run dev` | 開発サーバー起動 |
| `npm test` | テスト実行 |
| `npm run lint` | ESLint実行 |
| `npm run build` | 本番ビルド |
主要セクションまとめ
| セクション | 内容 | 例 |
|---|---|---|
| プロジェクト概要 | 何を作っているか | Eコマースサイトのフロントエンド |
| ディレクトリ構成 | フォルダ構造 | src/, components/, pages/ |
| 技術スタック | 使用技術 | React, TypeScript, Tailwind |
| コーディング規約 | ルール | strictモード、2スペースインデント |
| コマンド集 | よく使うコマンド | npm run dev, npm test |
避けるべき内容
| 内容 | 理由 |
|---|---|
| 秘密情報 | APIキー、パスワード等は絶対に書かない |
| Linter指示 | ESLint等の専用ツールで管理すべき |
| 変更履歴 | CHANGELOG.mdに分離する |
| 詳細な実装説明 | arch.md等のドキュメントに分離する |
| TODOリスト | todo.md等に分離する |
注意: CLAUDE.mdに秘密情報を書くと、セッション時にClaudeに送信されるため、情報漏洩のリスクがあります。絶対に書かないでください。
Global/Project/Localの使い分け
Claude Codeは3つのスコープでCLAUDE.mdを管理できます。
3層スコープの説明
| スコープ | ファイルパス | 用途 | Git管理 |
|---|---|---|---|
| Global | ~/.claude/CLAUDE.md |
全プロジェクト共通の個人設定 | ✗ |
| Project | ./CLAUDE.md |
プロジェクト固有の設定（チーム共有） | ✓ |
| Local | ./CLAUDE.local.md |
個人的なプロジェクト設定 | ✗ (.gitignore) |
優先順位と上書きルール
設定の優先順位は以下の通りです（高 → 低）。
-
Local —
./CLAUDE.local.md -
Project —
./CLAUDE.md -
Global —
~/.claude/CLAUDE.md
上位のファイルが下位のファイルの設定を上書きします。
使い分けガイドライン
Global (~/.claude/CLAUDE.md)
- 全プロジェクトで共通のコーディングスタイル
- 個人的な好み（コメントスタイル、変数命名等）
- よく使うコマンドのエイリアス
例
# 個人設定
## コーディングスタイル
- 2スペースインデント
- シングルクォート優先
- セミコロン省略
## 言語設定
- 全ての応答は日本語で
Project (./CLAUDE.md)
- プロジェクト固有の設計思想
- チーム全体で共有したいルール
- プロジェクトのディレクトリ構成
例
# プロジェクト設定
## 技術スタック
- React 18
- TypeScript 5
- Tailwind CSS
## アーキテクチャ
- Atomic Designを採用
- Custom Hooksでロジック分離
Local (./CLAUDE.local.md)
- 自分だけが使う開発環境設定
- ローカルのパス指定
- チームに共有しない個人的なメモ
例
# ローカル設定
## 開発環境
- ローカルAPIサーバー: http://localhost:3001
- テスト用DBパス: /Users/yourname/testdb
CLAUDE.mdを「育てる」発想
60-300行の推奨範囲
Claude Codeの公式ガイドでは、CLAUDE.mdを60-300行以内に保つことが推奨されています。
理由
- Claudeが確実に従える指示は150-200程度
- システムプロンプトで約50を使用済み
- 長すぎるとClaudeがランダムに指示を無視し始める
- 大きすぎると見落としが発生する
Progressive Disclosure（段階的開示）
CLAUDE.mdが肥大化してきたら、.claude/rules/ディレクトリにルールファイルを分割できます。
基本構成
your-project/
├── CLAUDE.md # メインの指示（60行以内）
└── .claude/
└── rules/
├── code-style.md # コードスタイル
├── testing.md # テスト規約
└── api-design.md # API設計
動的ロードの仕組み
YAMLフロントマターでpathsを指定すると、特定ファイル操作時のみルールがロードされます。
---
paths: src/api/**/*.ts
---
# API開発ルール
- 全APIエンドポイントは入力検証必須
- 標準エラーレスポンス形式を使用
この設定により、src/api/配下のTypeScriptファイルを操作する時だけ、このルールがコンテキストに読み込まれます。
継続的改善: Claudeの失敗から学ぶ
CLAUDE.mdは「生きたドキュメント」として育てていきます。
改善のシグナル
- 同じ訂正を2回したら、ファイルに追加すべきシグナル
- Claudeが誤った提案をした場合、WHYを追記する
- 新しいパターンを採用したら、すぐにCLAUDE.mdに反映
例: Claudeが何度もグローバル変数を提案してきた場合
## コーディング規約
- グローバル変数は禁止
- 理由: 過去にグローバル変数が原因でバグが発生したため、すべて関数スコープまたはモジュールスコープで管理
Tips:
#キーで指示を自動追加できます（Claude Code CLIの機能）。同じ訂正を繰り返したら、その場でCLAUDE.mdに追記しましょう。
注意: CLAUDE.mdが大きすぎるとClaudeが見落とします。60-300行を目安に、詳細はドキュメントに分離してください。
まとめ&次回予告
この記事でやったこと
- CLAUDE.mdの役割を理解した
-
/initコマンドでCLAUDE.mdを生成した - WHAT/WHY/HOWの3つの視点で内容を記述した
- Global/Project/Localの使い分けを理解した
- 「育てる」発想を持った
チェックリスト
CLAUDE.mdを作成したら、以下をチェックしてください。
- ファイルサイズは60-300行以内か
- プロジェクト固有の「変わった部分」を記述したか
- WHY（理由）を明記したか
- 秘密情報は含まれていないか
- よく使うコマンドを記載したか
コピペで使える完全テンプレート（TypeScript + React）
./CLAUDE.md
# プロジェクト概要
Eコマースサイトのフロントエンド。React + TypeScriptで実装。
> このファイルは変更ログとして使用しない。変更履歴はCHANGELOG.mdに記録すること。
## ディレクトリ構成
| ディレクトリ | 役割 |
|-------------|------|
| src/components/ | Reactコンポーネント（Atomic Design） |
| src/hooks/ | カスタムフック |
| src/api/ | API呼び出しロジック |
| src/types/ | TypeScript型定義 |
| src/utils/ | 汎用ユーティリティ |
## 技術スタック
- React 18
- TypeScript 5 (strictモード)
- Tailwind CSS
- Vite
- Vitest
## 設計原則
- TypeScript strictモード: 本番バグがimplicit anyから発生したため厳格化
- Atomic Design: Atoms, Molecules, Organisms, Templates, Pagesの5階層
- Custom Hooks: ビジネスロジックとUIを分離
- API層の分離: src/api/配下に集約し、コンポーネントから直接fetchしない
## コーディング規約
- 2スペースインデント
- シングルクォート優先
- セミコロン省略
- 関数コンポーネントはアロー関数で定義
- propsの型定義は必須
## よく使うコマンド
| コマンド | 説明 |
|---------|------|
| `npm run dev` | 開発サーバー起動 |
| `npm test` | テスト実行 |
| `npm run lint` | ESLint実行 |
| `npm run build` | 本番ビルド |
## 参考ドキュメント
- 詳細なアーキテクチャ: arch.md
- 変更履歴: CHANGELOG.md
- タスク管理: todo.md
次回予告
次回は「パーミッション＆Sandbox完全ガイド」を解説します。Claude Codeの安全性を保ちつつ、効率的に操作を自動承認する方法を紹介します。
連載一覧
- #1: インストールから"使える"初期設定まで
- #2: CLAUDE.mdの書き方と育て方 （本記事）
- #3: パーミッション＆Sandbox完全ガイド
- #4: Hooks実践テクニック
- #5: Skills入門
- #6: MCP活用術