CLAUDE.mdでプロジェクトに「記憶」を持たせる

あなたが複数のプロジェクトを同時に進めている状況を想像してみてください。先月のプロジェクトで判明した技術的な制約、チームの希望条件、既に試した解決策と失敗した理由…こうした情報の全てがClaude Codeのコンテキストから消えてしまいます。新しいセッションを始めるたびに、あなたは同じ説明を何度も繰り返すことになります。これは時間の浪費であり、判断の質低下を招きます。

ここで活躍するのがCLAUDE.mdという仕組みです。プロジェクトルートに配置された特別なマークダウンファイルに「プロジェクトの文脈」を記録しておくことで、Claude Codeは毎回のセッションでその情報を読み込み、あたかも前回の会話を覚えているかのように動作します。これはあなたとAIの関係を「その場限りの相談」から「継続的なパートナーシップ」へと変える力を持っています。

なぜプロジェクトに「記憶」が必要なのか

文脈の喪失による生産性低下

Claude Codeを使ってコーディングの支援を受けた経験があるなら、この課題に直面しているはずです。セッションが終わり、翌日新しくセッションを開くと、AIはあなたのプロジェクトの詳細をほぼ忘れています。「このプロジェクトではなぜこの技術を選んだのか」「過去にこの部分でトラブルがあったから、この方針で進めている」といった重要な背景情報を、毎回ゼロから説明する必要があります。

具体的に計算してみましょう。平均的なプロジェクトで、セッション開始時に文脈説明に費やす時間は5～15分です。週に3回新しいセッションを開くと、月間で60～180分（1～3時間）が単なる説明に消えます。これは年間で12～36時間。仮に時給3,000円で計算すれば、年間36,000～108,000円分の生産性が失われているということです。

判断の質が低下する理由

文脈がないAIの提案は、往々にして「一般的には良い解決策」になります。あなたのプロジェクト固有の制約条件を知らないため、最適な判断ができないのです。例えば「レガシーシステムとの互換性を保つ必要がある」という制約を忘れると、AIは最新のベストプラクティスだけを勧めてくる。その結果、せっかくもらった提案を実装できず、時間を無駄にしてしまいます。

CLAUDE.mdの正体：プロジェクトの「脳」を作る

CLAUDE.mdとは何か

CLAUDE.mdは、あなたのプロジェクトルートに配置するマークダウンファイルです。特別な名前のこのファイルをプロジェクトに含めておくと、Claude Codeはファイルを開く際に自動的にこれを読み込み、会話の文脈として活用します。

重要なポイントは、これがClaude Code特有の機能ではなく、Anthropic社が推奨する標準的な慣行だということです。多くのプロでこの仕組みを導入しており、実績のあるアプローチです。

何を記録するべきか

CLAUDE.mdに書くべき内容は、「あなたがAIに毎回説明している情報」です。具体的には以下の項目を想定してください：

• プロジェクトの目的と背景：何を作っているのか、なぜ作っているのか
• 技術スタック：使用言語、フレームワーク、ライブラリのバージョン
• アーキテクチャの制約：パフォーマンス要件、スケーラビリティの考慮事項
• 既知の課題と対応方針：過去に遭遇した問題と、なぜそう対応しているのか
• チームやステークホルダーの要望：ビジネス側の優先順位、使用禁止技術など
• 開発ガイドライン：命名規則、ファイル構成、コード品質の基準
• 外部システムとの連携情報：API仕様、認証方法、既知の互換性問題

CLAUDE.mdを実装する具体的な手順

ステップ1：プロジェクトルートでCLAUDE.mdを作成する

あなたのプロジェクトのルートディレクトリ（package.jsonやREADME.mdと同じ階層）に新しいファイルを作成します。Claude Codeでこれを実行する場合、ファイルエクスプローラを開いて直接作成することもできますし、Claude Codeに以下のようにお願いすることもできます：

「プロジェクトルートにCLAUDE.mdというファイルを作成してください」

Claude Codeはこのリクエストを理解し、正しい場所に正しい名前でファイルを生成します。

ステップ2：プロジェクト情報を段階的に記入する

CLAUDE.mdに記入する際は、一度に全てを完璧に書く必要はありません。むしろ、段階的に情報を追加していく方が現実的です。最初のセッションでは以下のような基本情報で十分です：

# Project Context

## Project Overview
- **Name**: [プロジェクト名]
- **Purpose**: [何を作っているか、簡潔に]
- **Status**: [進捗状況]

## Tech Stack
- Language: [使用言語]
- Framework: [フレームワーク]
- Key Libraries: [重要なライブラリ一覧]

## Known Constraints
- [制約条件1]
- [制約条件2]

## Decision Log
- [重要な判断と理由]

このテンプレートをベースに、あなたのプロジェクト固有の情報を埋めていきます。所要時間は15～30分程度が目安です。

ステップ3：セッションの都度、新しい発見を追記する

プロジェクトを進めると、新しい制約や決定事項が生まれます。例えば「このライブラリのバージョン3.0は互換性がないため、2.xを使い続ける」といった情報です。こうした気付きが出たら、その都度CLAUDE.mdに追記する習慣をつけましょう。

このプロセスは月に1～2時間程度の投資で済みます。一方で、その後のセッションでの説明時間を大幅に削減できるため、ROIは明確です。

実践例：異なるプロジェクトタイプごとのCLAUDE.md

例1：Webアプリケーション開発

# Project Context: E-commerce Platform

## Project Overview
- **Name**: ShopCart
- **Purpose**: B2B向けマルチテナント型ECプラットフォーム
- **Timeline**: 2024年Q3リリース予定
- **Status**: 開発中（認証機能と決済統合が完了）

## Tech Stack
- Backend: Node.js 20.x + Express.js
- Database: PostgreSQL 15
- Frontend: React 18 + TypeScript
- API: GraphQL (Apollo Server)

## Critical Constraints
- PCI DSSコンプライアンス必須（決済取り扱い）
- Stripe API連携が必須、stripe-nodeパッケージはv14.x
- レガシーシステムとのREST API互換性を保つ必要あり（3年間の段階的廃止予定）
- マルチテナント環境のため、テーブル設計に必ずtenant_idカラムを含める

## Known Issues & Decisions
1. **メモリリークの回避**: ストリーミング処理でメモリが逆流することが判明
   → 決定：Readable.from()で明示的に閉鎖する方式を採用

2. **認証方式**: JWT vs. Session
   → 決定：JWT採用。理由：マイクロサービス化を将来予定しているため

3. **ORM選定**: TypeORM vs. Prisma
   → 決定：Prisma 5.x採用。理由：スキーマのビジュアル管理とマイグレーション管理が優秀

このレベルの詳細があれば、Claude Codeは新機能提案時に「あ、このプロジェクトはPCI DSS対応が必須なんだ」と理解し、セキュリティを考慮した実装を提案できるようになります。

例2：データ分析・機械学習プロジェクト

# Project Context: Customer Churn Prediction

## Project Overview
- **Name**: ChurnGuard ML
- **Purpose**: SaaS企業の顧客流失予測モデル構築
- **Data Source**: PostgreSQL (customer_events, subscription_history tables)
- **Status**: データ前処理完了、モデル選定フェーズ

## Tech Stack
- Language: Python 3.11
- ML Framework: scikit-learn 1.3.0 (not TensorFlow)
- Data Processing: pandas 2.0 + polars for large datasets
- Deployment: FastAPI + Docker
- Environment: Ubuntu 22.04 LTS

## Data Constraints
- Training dataset: 50,000 samples, 12 features
- Class imbalance: 15% churn vs 85% retained (SMOTE必須)
- Missing values: 約5%のNaN値（listwise deletionで対応中）
- Target variable: binary (churned=1, retained=0)

## Performance Requirements
- Model training: 1時間以内に完了すること
- Prediction latency: <100msの要件あり
- Accuracy target: AUC-ROC > 0.85

## Team Context
- データサイエンティスト1名 + エンジニア2名
- 説明性が重視される（経営層への報告が多い）
- XGBoostは許可、ニューラルネットワークは許可されていない

このCLAUDE.mdがあれば、Claude Codeは「複雑な深層学習モデルを提案する」という無駄な提案をしなくなります。

例3：個人開発・副業プロジェクト

# Project Context: SideHustle Portfolio Site

## Project Overview
- **Name**: MyPortfolio2024
- **Purpose**: フリーランスの営業用ポートフォリオサイト
- **Target Audience**: 企業のWEB発注担当者
- **Status**: デザイン確定、実装開始

## Tech Stack
- Static Site: Next.js 14 (App Router)
- Styling: Tailwind CSS 3.3
- Hosting: Vercel (free plan)
- CMS: Not needed (マークダウンベースで十分)

## Budget & Constraints
- **Monthly cost limit**: ¥0 (Vercel free + GitHub free)
- **Development time**: 週3～5時間しか割けない
- Maintenance: 極力自動化（デプロイ自動化、記事更新の手間削減）

## Personal Preferences
- TypeScript: 必須（スキルアピール）
- 新しい技術は避ける（保守しやすさ重視）
- SEO最適化は重視（Google検索流入が重要）
- ダークモード対応は必須

## Completed
- ✅ ランディングページのデザイン
- ✅ プロジェクト一覧の情報設計

## Next Steps
- [ ] プロジェクト詳細ページのテンプレート作成
- [ ] ブログ機能の実装

このような個人プロジェクトでも、情報をCLAUDE.mdに整理しておくことで、何ヶ月か後に「あ、どういう方針だったっけ」という悩みから解放されます。

CLAUDE.mdを活用するテクニック

テクニック1：Decision Logで判断の背景を記録

CLAUDE.mdに「何をしたか」だけでなく「なぜそうしたのか」を記録することが重要です。特に「Why」は数ヶ月後に自分が忘れやすい情報です。

## Decision Log

### Decision: Framework選択
**Date**: 2024-01-15
**Topic**: フロントエンドフレームワークの選定
**Options Considered**: Vue 3, React 18, Svelte
**Decision**: React 18を採用
**Rationale**:
- 既存チームの習熟度が高い
- ライブラリエコシステムが豊富
- 企業の採用市場が広い（将来の採用活動で有利）

**Rejected & Why**: 
- Vue: フレームワーク需要が日本市場で限定的
- Svelte: チームにノウハウがなく、学習コスト > メリット

---

### Decision: 状態管理ライブラリ
**Date**: 2024-02-03
**Topic**: Redux vs Zustand vs Jotai
**Decision**: Zustand採用
**Rationale**: 
- Redux: ボイラープレートコードが多い（小～中規模プロジェクトには過剰）
- Jotai: 参考資料が英語メインで、日本語ドキュメントが不足
- **Zustand**: シンプルさと学習曲線のバランスが最適

このように記録しておくことで、Claude Codeは「なぜこのプロジェクトはReduxではなくZustandなのか」を理解し、提案の方向性を調整できます。

テクニック2：セッション毎の進捗を記録する

CLAUDE.mdに「今どこまで進んだのか」を記録しておくと、前回のセッションからの継続がスムーズになります。

## Development Progress

### Current Session (2024-03-10)
**Started with**: 認証フロー実装の引き継ぎ
**Accomplished**:
- ✅ JWTリフレッシュトークン機能実装
- ✅ ログアウト時のトークンクリア処理実装
- ⏳ テストケース追加（50%完了）

**Blockers**: 
- クッキーのSameSite属性がローカル開発環境で動作しない
  → 決定：localhost開発時はSameSite=Noneで回避（本番はStrict）

**Next Session Priority**:
1. テストケースの完了（見積り：30分）
2. エラーハンドリングの統一（見積り：45分）

これがあると、次回のセッション開始時に「前回どこまで行ったっけ？」という時間ロスが完全になくなります。実際にはセッション開始時の文脈確認に5分以上かかることが普通ですが、これで0分に短縮できます。

テクニック3：「やってはいけないこと」を明示的に記録

AIは提案をするとき、一般的なベストプラクティスを基準に考えます。しかし、あなたのプロジェクトには「この技術は使わない」という制約があるかもしれません。こうした禁止事項を明示的に記録することが重要です。

## 禁止・避けるべき技術・パターン

### 言語・フレームワーク層
- ❌ Python 2.x（非対応）
- ❌ ニューラルネットワーク系フレームワーク（経営判断）
- ❌ GraphQL（既存REST APIとの互換性維持が難しい）

### ライブラリ・パッケージ層
- ❌ moment.js（保守停止中。代わりにday.jsを使用）
- ⚠️ 新しいメジャーバージョン（stability重視のため、N-2バージョンまで）

### アーキテクチャ・パターン層
- ❌ マイクロサービスアーキテクチャ（現段階ではオーバーエンジニアリング）
- ❌ サーバーサイドレンダリング（CDNキャッシュ戦略を複雑化させる）

### 理由
チームの保守性と将来の採用予定考慮が優先。最新技術より、チーム全員が理解・保守できることを重視

このセクションがあると、Claude Codeが「いや、GraphQLを使った方が…」という提案をすることがなくなります。

CLAUDE.mdを運用する現実的な方法

更新