CLAUDE.mdでプロジェクトの記憶を作る

このレッスンで学ぶこと

CLAUDE.mdの役割と仕組みを理解する
CLAUDE.mdの配置場所と読み込み優先順位を知る
プロジェクトに適したCLAUDE.mdを作成できるようになる

前提条件

Lesson 2 を完了し、Claude Codeで基本的なタスクを実行した経験があること
開発中のプロジェクト（どんな言語・フレームワークでもOK）があること

CLAUDE.mdとは何か

Claude Codeを使っていると、毎回同じことを説明していることに気づくかもしれません。「うちのプロジェクトではTypeScriptを使っていて、テストはJestで書いていて、コミットメッセージは日本語で...」といった説明です。

CLAUDE.mdは、こうしたプロジェクトの情報をファイルに書いておくことで、Claude Codeが毎回のセッション開始時に自動的に読み込んでくれる仕組みです。いわば、Claude Codeの「プロジェクトメモリ」です。

CLAUDE.mdがあると、Claudeはプロジェクトの規約やルールを理解した状態で作業を始めてくれます。「インデントはスペース2つで」「テストはVitest」「コミットメッセージは日本語」などのルールをいちいち伝える必要がなくなります。

配置場所と読み込み優先順位

CLAUDE.mdはいくつかの場所に配置でき、場所によってスコープ（適用範囲）が異なります。

スコープ	配置場所	用途	共有対象
ユーザー全体	`~/.claude/CLAUDE.md`	すべてのプロジェクトで使いたい個人的な好み	自分だけ
プロジェクト	`./CLAUDE.md` または `./.claude/CLAUDE.md`	チームで共有するプロジェクトのルール	Gitで共有
ローカル	`./CLAUDE.local.md`	個人的なプロジェクト固有のメモ	自分だけ

最初はプロジェクトルートだけでOK

まずはプロジェクトのルートディレクトリに CLAUDE.md を1つ作るところから始めましょう。複数の場所に配置する必要が出てくるのは、チーム開発や複数プロジェクトを扱うようになってからです。

読み込みの仕組み

Claude Codeは起動時に、現在のディレクトリから上位のディレクトリに向かってCLAUDE.mdファイルを探し、すべてを読み込みます。たとえば project/src/ でClaude Codeを起動した場合、project/src/CLAUDE.md と project/CLAUDE.md の両方が読み込まれます。

サブディレクトリ（下位フォルダ）にあるCLAUDE.mdは、Claudeがそのフォルダ内のファイルを読み込む際にオンデマンドで読み込まれます。

CLAUDE.mdに書くべき内容

CLAUDE.mdには「Claudeが毎回のセッションで知っておくべき情報」を書きます。具体的には、以下のようなカテゴリに分けて整理すると効果的です。

1. ビルド・テストコマンド

Claudeがコードを自分で検証できるよう、プロジェクト固有のコマンドを記載します。

# ビルド・テスト
- ビルド: `npm run build`
- テスト全体: `npm test`
- 単一テスト: `npm test -- --grep "テスト名"`
- リント: `npm run lint`
- 型チェック: `npx tsc --noEmit`

2. コーディング規約

チームのコーディングスタイルを明記します。Claudeがコードを読めば推測できる標準的な規約は省き、プロジェクト固有のルールだけを書くのがポイントです。

# コードスタイル
- ES Modules（import/export）を使用する。CommonJS（require）は使わない
- インデントはスペース2つ
- 変数名・関数名はcamelCase、コンポーネント名はPascalCase
- コメントは日本語で書く

3. プロジェクト構造

Claudeがファイルを探しやすくなるよう、ディレクトリ構造の概要を書きます。

# ディレクトリ構造
- `src/api/` - APIハンドラー
- `src/components/` - Reactコンポーネント
- `src/hooks/` - カスタムフック
- `src/utils/` - ユーティリティ関数
- `tests/` - テストファイル（src/と同じ構造）

4. Git運用ルール

コミットやブランチの規約を記載します。

# Git運用
- コミットメッセージは日本語で書く
- ブランチ名: feature/*, fix/*, hotfix/*
- mainブランチへの直接コミットは禁止

5. 禁止事項

やってはいけないことを明確に記載します。

# 禁止事項
- .envファイルや認証情報をコミットに含めない
- any型を使わない（やむを得ない場合はコメントで理由を書く）
- console.logを本番コードに残さない

書きすぎに注意

CLAUDE.mdは200行以下を目安にしましょう。長すぎるとコンテキスト（Claudeが参照できる情報のまとまり）を圧迫し、指示が無視される原因になります。「この指示を消したらClaudeが間違いを犯すか?」と自問し、NOなら削除しましょう。

実践: CLAUDE.mdのテンプレート

以下は、多くのプロジェクトで使えるCLAUDE.mdのテンプレートです。自分のプロジェクトに合わせてカスタマイズして使いましょう。

# プロジェクト概要
<!-- プロジェクトの説明を1〜2行で -->
 
# ビルド・テスト
- ビルド: `コマンドをここに`
- テスト: `コマンドをここに`
- リント: `コマンドをここに`
 
# コードスタイル
- 言語: TypeScript
- フレームワーク: React / Next.js
- インデント: スペース2つ
- インポート: ES Modules（import/export）
- 命名規則: 変数はcamelCase、コンポーネントはPascalCase
 
# Git運用
- コミットメッセージは日本語で記述する
- mainブランチへの直接コミット禁止
 
# 禁止事項
- any型を使わない
- .envや認証情報をコミットに含めない
- console.logを本番コードに残さない

`/init` コマンドで自動生成する

CLAUDE.mdをゼロから書くのが面倒な場合は、/init コマンドを使うとClaudeがプロジェクトを分析して自動生成してくれます。

プロジェクトのルートディレクトリでClaude Codeを起動する

cd /path/to/your/project
claude

/init コマンドを実行する

/init

Claudeがプロジェクトのファイル構成やpackage.json等を分析し、ビルドコマンド・テストフレームワーク・コードパターンを検出してCLAUDE.mdを作成します。

生成された内容を確認・修正する

自動生成されたCLAUDE.mdの内容を確認し、プロジェクト固有のルールや禁止事項を追加しましょう。/init はあくまで出発点です。チームの規約や暗黙のルールは手動で追記する必要があります。

既存のCLAUDE.mdがある場合

既にCLAUDE.mdが存在する場合、/init は上書きせずに改善を提案してくれます。安心して実行できます。

CLAUDE.mdの効果: before/after

CLAUDE.mdがあるとないとで、Claudeの振る舞いがどう変わるかを見てみましょう。

CLAUDE.mdなしの場合

> ユーザー入力のバリデーション関数を書いて
 
Claudeの出力:
- JavaScript（CommonJS）で書かれる（プロジェクトはTypeScriptなのに）
- テストが付かない（プロジェクトではテスト必須なのに）
- 英語コメント（チームは日本語コメントなのに）

CLAUDE.mdありの場合

> ユーザー入力のバリデーション関数を書いて
 
Claudeの出力:
- TypeScript（ES Modules）で書かれる
- Vitestのテストコードが一緒に生成される
- 日本語のコメント付き
- プロジェクトの命名規則に従っている

このように、CLAUDE.mdを整備しておくと、プロジェクトの「当たり前」をClaudeが理解した上でコードを生成してくれます。

よくある間違い・アンチパターン

1. 情報を詰め込みすぎる

CLAUDE.mdにプロジェクトのすべてを書こうとするのはアンチパターンです。Claudeがコードを読めば分かることは省きましょう。

書くべきもの	書かなくてよいもの
Claudeが推測できないビルドコマンド	標準的な言語仕様の説明
デフォルトと異なるコードスタイルルール	コードを読めば分かる規約
プロジェクト固有のアーキテクチャ決定	詳細なAPIドキュメント（リンクで十分）
よくある落とし穴や暗黙のルール	頻繁に変わる情報

2. 曖昧な指示を書く

「コードを適切にフォーマットする」のような曖昧な指示は効果が薄いです。「インデントはスペース2つ」のように、具体的に書きましょう。

3. 矛盾する指示がある

複数のCLAUDE.mdファイルやルールファイルで矛盾した指示があると、Claudeはどちらかを任意に選んでしまいます。定期的に内容を見直して、古い指示や矛盾を取り除きましょう。

チームでの共有方法

CLAUDE.md（チーム共有）

プロジェクトルートの CLAUDE.md はGitにコミットしてチーム全員で共有します。コーディング規約やビルドコマンドなど、プロジェクト共通のルールを書きます。

CLAUDE.local.md（個人用）

自分だけの設定は CLAUDE.local.md に書き、.gitignore に追加しておきます。個人的なサンドボックスURL、好みのテストデータなどが該当します。

# .gitignoreに追加
echo "CLAUDE.local.md" >> .gitignore

.claude/settings.json（技術的な制御）

CLAUDE.mdが「Claudeへの行動ガイダンス」であるのに対し、.claude/settings.json は「技術的な制御」を担います。

用途	設定先
コードスタイル、テスト方針、ワークフロー	CLAUDE.md
許可・拒否するコマンドのルール	.claude/settings.json
MCP（外部ツール連携）の設定	.mcp.json

CLAUDE.mdは育てていくもの

最初から完璧なCLAUDE.mdを書く必要はありません。Claudeが間違えるたびに「次から間違えないように」とルールを追加し、不要になったルールは削除する。このサイクルを繰り返すことで、プロジェクトに最適化されたCLAUDE.mdが育っていきます。

よくある質問

Q: CLAUDE.mdの指示をClaudeが無視することはある?

あります。CLAUDE.mdはシステムプロンプト（最優先の命令）ではなく、コンテキストとして読み込まれます。具体的で簡潔な指示ほど従われやすく、曖昧で長い指示は無視されやすくなります。絶対にブロックしたい操作がある場合は、.claude/settings.json のdenyリストやHooksの仕組みを検討しましょう。

Q: `/init` で生成したCLAUDE.mdはそのまま使っていい?

出発点としては十分ですが、そのまま使うのはおすすめしません。チーム固有のルールや暗黙の規約は /init では検出されないため、手動で追記する必要があります。

Q: CLAUDE.mdはどのくらいの頻度で更新すべき?

コードと同じように扱いましょう。Claudeが同じ間違いを2回犯したらルールを追加する、コードレビューでClaudeの出力に繰り返し問題が見つかったら指示を見直す、といった形が自然です。

まとめ

このレッスンでは、以下のことを学びました。

CLAUDE.mdの役割: Claudeが毎セッション自動で読み込む「プロジェクトメモリ」
配置場所: プロジェクトルート（チーム共有）、ホームディレクトリ（個人全体）、CLAUDE.local.md（個人×プロジェクト）
書くべき内容: ビルドコマンド、コーディング規約、Git運用ルール、禁止事項
自動生成: /init コマンドで出発点を作り、手動で育てていく
アンチパターン: 詰め込みすぎ、曖昧な指示、矛盾する指示を避ける
チーム共有: CLAUDE.mdはGit管理、個人設定はCLAUDE.local.mdに分離

次のステップ

次のレッスンでは、コミットメッセージの生成やPR作成、コードレビュー依頼など、Claude Codeを日常の開発業務に組み込む実践的なワークフローを学びます。

Lesson 5: 明日から使える日常ワークフローに進みましょう。