CLAUDE.md — プロジェクトの「記憶」を設計する

CLAUDE.mdとは何か

Claude Codeは、毎回の会話がリセットされるAIです。 昨日決めた方針も、プロジェクトのルールも、次のセッションでは忘れている。CLAUDE.mdは、この問題を解決するための仕組みです。

プロジェクトのルート（または~/.claude/配下）に配置するマークダウンファイルで、 Claude Codeが会話を開始するたびに自動で読み込む設定ファイルです。 いわばAIに対する「引き継ぎメモ」であり、プロジェクトの記憶を外部化する手段です。

3つのスコープ — どこに置くかで影響範囲が変わる

CLAUDE.mdには3つの配置場所があり、それぞれ影響範囲が異なります。 正しく使い分けることが、効果的な運用の第一歩です。

1. ユーザーレベル（~/.claude/CLAUDE.md）

ホームディレクトリの.claude/フォルダに配置します。そのユーザーの全セッションに適用されるグローバル設定です。

• コミュニケーションの言語設定（「日本語で応答すること」）
• 個人の作業スタイルや好み
• 全プロジェクト共通のルール

2. プロジェクトレベル（./CLAUDE.md）

プロジェクトのルートディレクトリに配置します。そのプロジェクトで作業する全員に適用されます。 Gitリポジトリにコミットすれば、チーム全体で共有できます。

• 技術スタック・アーキテクチャの説明
• コーディング規約（命名規則、ファイル構成）
• 禁止事項（本番DBへの直接アクセス禁止、など）
• テストの実行方法、デプロイ手順

3. ディレクトリレベル（./src/CLAUDE.md など）

サブディレクトリに配置します。そのディレクトリ以下で作業する場合にのみ適用されます。 大規模プロジェクトでモジュールごとにルールが異なる場合に有効です。

• フロントエンド固有の規約（src/frontend/CLAUDE.md）
• API設計のルール（src/api/CLAUDE.md）
• テストディレクトリの方針（tests/CLAUDE.md）

書きすぎると逆効果になる理由

CLAUDE.mdの設計で最もよくある失敗は、書きすぎることです。

CLAUDE.mdの内容はセッション開始時にコンテキストウィンドウに読み込まれます。 つまり、書いた分だけAIの「作業机」のスペースを消費するということです。 導入ガイドのセクション01で説明した100万トークンのコンテキストウィンドウは広大ですが、無限ではありません。

実運用で見られる具体的な問題は以下の通りです。

• 指示の矛盾: ルールが多すぎると互いに矛盾し、AIがどちらに従うべきか判断できなくなる
• 重要度の希薄化: 本当に重要なルールが大量の補足に埋もれ、守られなくなる
• コンテキストの圧迫: CLAUDE.mdが大きいほど、実際の作業に使える文脈が減る

実運用テンプレート

以下は、実際のプロジェクトで使用しているCLAUDE.mdの構成例です。 コピーしてそのまま使うのではなく、プロジェクトの実情に合わせてカスタマイズしてください。

# プロジェクト名

## 概要
- 何のプロジェクトか（1〜2文で）
- 技術スタック: Next.js 15 / TypeScript / Supabase / Vercel

## アーキテクチャ
- src/app/ — App Router ページ
- src/components/ — 共有コンポーネント
- src/lib/ — ユーティリティ、API クライアント
- supabase/migrations/ — DBマイグレーション

## コーディング規約
- TypeScript strict mode
- コンポーネントは関数コンポーネント + hooks
- CSS Modules を使用（Tailwind は不使用）
- テストは Vitest + React Testing Library

## 禁止事項
- 本番データベースへの直接クエリ禁止
- .env ファイルをコミットしない
- node_modules/ をコミットしない

## テスト
- `npm run test` で全テスト実行
- PR前に必ず `npm run lint && npm run test` を通すこと

## デプロイ
- main ブランチへのマージで Vercel に自動デプロイ
- ステージング: preview ブランチ

効果的なCLAUDE.mdを書くための5つの原則

原則1：「何をするか」ではなく「何をしないか」を書く

AIは多くのことをデフォルトでうまくやります。 わざわざ書くべきは、AIが間違えやすいポイントや、プロジェクト固有の制約です。 「TypeScriptで書け」は不要（すでにTypeScriptプロジェクトなら自明）ですが、 「Tailwindは使わずCSS Modulesを使え」は書く価値があります。

原則2：理由を添える

「本番DBに直接クエリを投げない」だけでなく、 「本番DBに直接クエリを投げない（過去にデータ破損インシデントがあったため）」と書く。 理由があるとAIは指示をより正確に解釈し、エッジケースでも適切に判断できます。

原則3：コードで示せることはコードで示す

「APIレスポンスは統一フォーマットで返すこと」と文章で書くより、 実際のフォーマット例を1つ貼る方がAIには伝わります。 抽象的な指示より、具体的な例が効きます。

原則4：定期的に棚卸しする

プロジェクトは変化します。3ヶ月前のルールが今も有効とは限りません。 月に1回程度、CLAUDE.mdを見直し、不要になったルールを削除してください。削除する勇気が、CLAUDE.mdの品質を維持する最大の秘訣です。

原則5：チームでレビューする

CLAUDE.mdはコードと同じようにGitで管理し、PRでレビューするのが理想です。 一人の思い込みでルールが増えるのを防ぎ、チーム全体で合意された「AIへの引き継ぎ」になります。

よくある失敗パターンと対処法

失敗1：全社共通のCLAUDE.mdを作ろうとする

プロジェクトごとに技術スタックもルールも異なります。 全社共通にしようとすると、抽象的で役に立たない内容になるか、 特定プロジェクトにしか当てはまらないルールが他のプロジェクトを汚染します。

対処法: ユーザーレベル（~/.claude/CLAUDE.md）は言語設定など最小限に留め、 具体的なルールはプロジェクトレベルに書く。

失敗2：CLAUDE.mdに「全てのドキュメント」を入れる

API仕様書、設計ドキュメント、議事録…全てをCLAUDE.mdに入れたくなる気持ちは分かりますが、 これではコンテキストウィンドウを無駄に消費するだけです。

対処法: CLAUDE.mdには概要とファイルパスの参照だけ書く。 「API仕様はdocs/api-spec.mdを参照」のように、必要に応じてAIが読みに行ける形にする。

失敗3：書いたまま放置する

最初に張り切って書いたCLAUDE.mdが、半年後にはプロジェクトの実態と乖離している。 古い情報はAIの出力品質を直接下げるため、放置は積極的に有害です。

対処法: スプリントレトロスペクティブやPRレビューのタイミングでCLAUDE.mdの見直しを習慣化する。

導入ステップ

CLAUDE.mdの導入は段階的に進めるのが効果的です。

• Week 1: まず最小限の内容（プロジェクト概要、技術スタック、禁止事項）で始める。 完璧を目指さず、3〜5項目で十分です。
• Week 2-3: 日々の運用で「AIが間違えた箇所」「毎回説明し直している内容」をCLAUDE.mdに追記していく。 実際の問題から逆算して育てるのが最も効率的です。
• Week 4: 一度棚卸し。重複や矛盾を整理し、チームメンバーにレビューしてもらう。
• 以降: 月1回の定期見直しを習慣化。不要なルールは削除し、スリムな状態を維持する。