🤖
AIのメモリ管理（CLAUDE.md）ってどう使えばいいの？
CLAUDE.mdに書くべき内容：世界のベストプラクティス
データに基づく頻出内容（30以上の実例から）
調査した実例から、頻出度が高い順：
1. プロジェクトコンテキスト/概要（95%）
- プロジェクトの目的・目標
- ドメイン固有の用語
- なぜこのプロジェクトが存在するか
2. 技術スタック（92%）
- 使用言語・フレームワーク・バージョン
- 主要な依存関係
- 「何を使っているか」の一覧
3. コードスタイルと規約（88%）
- インポート/エクスポートパターン
- 命名規則
- プロジェクト固有のパターン
- ただし: Prettierで実施できるものは除外
4. 開発ワークフロー（85%）
- ブランチ戦略
- コミットメッセージフォーマット
- PR/レビュープロセス
5. 共通コマンド（83%）
- ビルド、テスト、デプロイコマンド
- よく使う操作
2つの主要なアプローチ
世界には2つの異なる哲学が存在：
アプローチA: 技術仕様書型（多数派）
# プロジェクト概要
Eコマースプラットフォーム
# 技術スタック
- Next.js 14
- PostgreSQL
- Stripe
# ディレクトリ構造
src/
├── app/
├── components/
└── lib/
# コーディング規約
- TypeScript strict mode
- 関数コンポーネントのみ
特徴:
- 目的: プロジェクトの「What」を説明
- 対象: 新しいコントリビューターのオンボーディング的
- トークン: 多め（200-500行が一般的）
アプローチB: 協働ルール型（少数派だが強力）
# 基本原則
- 正しさ > 速さ
- すべての操作前に承認を得る
- 思考プロセスを説明
# 開発フロー
1. 要件確認
2. 設計提案
3. 差分提示
4. 承認
5. 実行
# 禁止事項
- 自律的なファイル変更
- 説明なしの提案
特徴:
- 目的: AIとの「How」を定義
- 対象: 個人的・規範的なルール
- トークン: 少なめ（100-200行）
- 代表例: Jesse Vincent氏、Tyler Burnam氏
Anthropic公式の推奨
公式ドキュメントと実践者の声から導き出されたベストプラクティス：
✅ 書くべきもの
1. プロジェクト固有の情報
他のプロジェクトでは通用しない、このプロジェクトだけのルール
2. AIが判断に迷う部分
「この場合はAパターン、この場合はBパターン」のような判断基準
3. 禁止事項/保護領域
- 「このディレクトリは触るな」
- 「このファイルは絶対に変更するな」
4. ツールで実施できないパターン
- コードフォーマットはPrettierに任せる
- 「どういう設計思想か」はCLAUDE.mdに書く
5. docs/へのポインタ
詳細は外部ファイル、CLAUDE.mdには「どこを見るか」だけ
❌ 書かないべきもの
1. 決定論的ツールが実施できること
- ❌ 「2スペースインデント」→ Prettierで設定
- ❌ 「import順序」→ eslint-plugin-import で設定
2. 自明な情報
- ❌ 「testsフォルダにはテストがある」
3. 長い物語的説明
- ❌ ジュニア開発者向けのチュートリアルではない
4. 変化しやすい詳細
- ❌ APIエンドポイントURL（環境変数に）
- ❌ 特定のバグ修正（コミットメッセージに）
理想的な構造：3層アーキテクチャ
調査と公式推奨を統合すると、理想的なCLAUDE.mdは3層構造：
第1層: コア原則（20-30行）
- プロジェクトの哲学
- AIとの協働ルール
- 絶対に守るべき原則
第2層: 技術コンテキスト（40-60行）
- 技術スタック（簡潔に）
- プロジェクト構造（概要のみ）
- 重要なコマンド
第3層: ドキュメント参照（20-30行）
-
docs/構造の説明 - 詳細情報の参照先
- 外部リソースへのポインタ
合計: 100-150行が理想
実例: Harper Reed氏のチーム実装
実際の成功事例：
# プロジェクト
AI駆動のeコマースプラットフォーム
# 技術スタック
Next.js 14, Supabase, Stripe
# コア原則
- TDD必須（テストファースト）
- すべての変更にレビュー必須
- docs/を常に最新に保つ
# ドキュメント
- docs/architecture.md - システム設計
- docs/api.md - API仕様
- docs/deployment.md - デプロイ手順
# 禁止
- mainへの直接push
- テストなしのコミット
- ハードコードされたシークレット
# コマンド
npm run dev - 開発
npm run test - テスト
npm run deploy - デプロイ
成果:
- 簡潔（約80行）
- 詳細はdocs/に分離
- 実行可能な指示のみ
- 結果: チーム全体で一貫した品質達成、過去最高のテストカバレッジ
内容配分の推奨バランス
理想的な配分：
- 協働ルール（How）: 50%
- 技術コンテキスト（What）: 30%
- ドキュメント参照: 20%
協働ルール重視の場合（個人開発者・学習重視）
- 協働ルール: 60%
- 技術コンテキスト: 25%
- ドキュメント参照: 15%
技術仕様重視の場合（チーム開発・オンボーディング重視）
- 協働ルール: 40%
- 技術コンテキスト: 40%
- ドキュメント参照: 20%
トークン効率の重要性
CLAUDE.mdの内容はすべてのプロンプトに前置されるため：
トークン消費の目安
- よく最適化された: 1-3K トークン（100-150行）
- 典型的: 2-5K トークン（150-250行）
- 肥大化（問題あり）: 10K+ トークン（500行以上）
最適化の原則
- 段落より箇条書き（90%のファイルで採用）
- 具体的で指示的（「適切に」ではなく「2スペースで」）
- 冗長性を削減
- 外部ドキュメントへの参照を活用
継続的改善のサイクル
CLAUDE.mdは「作成して忘れる」ものではなく、生きたドキュメント：
観察すべき指標
機能している兆候
- 初回成功率の増加
- 修正のやり取りが少なくなる
- AI生成コード間での一貫したスタイル
- 基準についての明確化質問が減少
改善が必要な兆候
- Claudeが明記されたルールを繰り返し違反
- パターンを常に再説明する必要がある
- 生成されたコードがプロジェクトスタイルと不一致
- 禁止されたファイル/領域を変更
改善のアクション
- Claudeが無視するセクション → 削除または書き直し
- 繰り返し説明すること → CLAUDE.mdに追加
- 効果のないルール → より具体的に書き直す
- 肥大化した内容 → サブディレクトリのCLAUDE.mdに分割
階層化戦略
大規模プロジェクトでは、複数のCLAUDE.mdファイルを配置：
project/
├── CLAUDE.md # ルート：全体原則
├── docs/
│ └── CLAUDE.md # ドキュメント固有
├── src/
│ ├── CLAUDE.md # ソースコード全般
│ ├── components/
│ │ └── CLAUDE.md # コンポーネント固有
│ └── api/
│ └── CLAUDE.md # API固有
└── tests/
└── CLAUDE.md # テスト固有
優先順位: より具体的な（ネストされた）ファイルが優先される
推奨テンプレート構造
# 基本原則
[20-30行: プロジェクト哲学、AIとの協働ルール]
# プロジェクト概要
[10-15行: 目的、ドメイン、目標]
# 技術スタック
[10-15行: 言語、フレームワーク、主要ライブラリ]
# プロジェクト構造
[15-20行: ディレクトリ概要、特殊ファイル]
# 開発ワークフロー
[20-30行: ブランチ戦略、コミット規約、レビュー]
# コーディング規約
[15-20行: プロジェクト固有のパターンのみ]
# 禁止事項
[10-15行: 触ってはいけないもの、アンチパターン]
# ドキュメント
[10-15行: docs/構造、参照先]
# 作業開始時の確認
[5-10行: チェックリスト]
合計: 120-170行
まとめ：理想的なCLAUDE.mdの条件
- ✅ 簡潔: 100-150行
- ✅ スキャン可能: 15-20秒で全体把握
- ✅ 実行可能: すべての内容が具体的な指示
- ✅ プロジェクト固有: 他では通用しない情報のみ
- ✅ 参照主義: 詳細はdocs/に分離
- ✅ 生きたドキュメント: 継続的に改善
- ✅ 階層化: 大規模プロジェクトはサブディレクトリに分割
- ✅ トークン効率: 箇条書き中心、冗長性なし
参考リソース
- Anthropic公式: Claude Code Best Practices
- 公式ドキュメント: Claude Code Memory
- コミュニティ事例: awesome-claude-code
- テンプレート: claude-code-template
Discussion