Claude Codeを使い込むほど、ある違和感が大きくなっていきます。
「なぜ毎回、同じ説明をしているんだろう？」という感覚です。
プロジェクトの背景、設計の意図、使っている技術スタック。
何度も伝えているはずなのに、新しいセッションを開くたびにClaudeは「初対面」のような反応を返してきます。
これは仕様上、仕方のないことです。
しかし、この繰り返しが生産性を確実に削っていきます。
毎回「初対面」になるClaude対話の正体
Claude Codeには、セッションをまたいで文脈を保持する仕組みがいくつか用意されています。
1つは /memory コマンドによるグローバルメモリ。
もう1つが、今回の主役である CLAUDE.md です。
CLAUDE.mdはプロジェクトのルートに置いておくと、Claudeが自動的に読み込んでくれるファイルです。
多くの開発者がここに技術スタックやディレクトリ構成を書いています。
ところが、これだけでは不十分でした。
技術スタックを書いたCLAUDE.mdを用意しても、Claudeの回答は浅いままです。
「React + TypeScriptで構成されています」と書いても、なぜその構成を選んだのか、どんな設計思想があるのかは伝わりません。
CLAUDE.mdは「設定ファイル」ではない
最初の頃、CLAUDE.mdを「一度書いたら完成する設定ファイル」だと思っていました。
技術スタック、ディレクトリ構成、コーディング規約。必要な情報を一通り書けば、あとはClaudeがよしなにやってくれるはずだと。
しかし、この考え方では限界がすぐに来ます。
設計意図は汲んでくれないし、プロジェクト固有の文脈は理解してくれません。
「このプロジェクトではこういう理由でこのパターンを使っている」という暗黙知は、設定ファイル的な記述では伝わらないのです。
CLAUDE.mdを「完成させるもの」と考えている限り、この問題は解決しません。
必要なのは、発想の転換でした。
「育てる」という発想への転換
転機になったのは、「Claudeが勘違いした瞬間を、そのままCLAUDE.mdに書く」という運用に変えたことです。
たとえば、Claudeが「このプロジェクトではReduxを使っていますね」と言ってきたとします。
実際にはContext APIを意図的に選んでいる。そこで訂正するだけでなく、CLAUDE.mdにこう追記します。
## 状態管理について
このプロジェクトではReduxではなくContext APIを使用しています。
理由：小規模アプリケーションであり、Reduxのボイラープレートはオーバーキル。こうやって「勘違いされたこと」を積み重ねていくと、CLAUDE.mdが徐々に「このプロジェクト固有の文脈集」に育っていきます。
説明し直す回数が減り、設計の一貫性が保たれ、思考がプロジェクトに残るようになりました。
CLAUDE.mdの階層構造を活用する
CLAUDE.mdは実は階層的に読み込まれます。
~/.claude/CLAUDE.md— 全プロジェクト共通の設定（コーディングスタイルの好みなど）- プロジェクトルートの
CLAUDE.md— プロジェクト固有の設計方針 - サブディレクトリの
CLAUDE.md— 特定機能やモジュール固有の注意点
たとえば、グローバル設定には「日本語で回答して」「コミットメッセージは英語で」といった個人の好みを書いておき、プロジェクトごとの設計思想は各プロジェクトのCLAUDE.mdに書く、という使い分けができます。
書くべきは「察してほしいこと」
CLAUDE.mdに書くべき内容は、「一般的な技術情報」ではありません。
それはClaudeがすでに知っています。書くべきは「このプロジェクトで察してほしいこと」です。
具体的には、以下のような内容が効果的です。
- なぜその技術を選んだか：「Prismaを使っているのは、型安全性を重視しているため」
- やらないと決めたこと：「CSSフレームワークは使わない方針。理由は学習目的のため」
- 過去の失敗から学んだこと：「以前、この箇所でメモリリークを起こしたので注意」
- 命名規則の意図：「handleXxxは副作用あり、getXxxは純粋関数として命名している」
技術スタックの羅列よりも、こうした「判断の理由」を書く方が、Claudeの理解度は格段に上がります。
プロジェクト別テンプレート
プロジェクトの性質によって、CLAUDE.mdに書くべき内容は変わります。
ここでは3つのパターンを紹介します。
個人開発プロジェクト
## このプロジェクトについて
個人開発のタスク管理アプリです。収益化は考えていません。
## 設計方針
- シンプルさを最優先。機能追加より既存機能の洗練を重視
- テストは主要なロジックのみ。UIテストは書かない
- 完璧より「動くもの」を優先
## よく使うコマンド
- 開発サーバー: `npm run dev`
- ビルド: `npm run build`
## よくある勘違い
- これは業務用ではないので、エンタープライズ級の設計は不要コンテンツ制作プロジェクト
## このプロジェクトについて
技術ブログの原稿管理リポジトリです。
## 文体ルール
- 「です・ます調」で統一
- 1段落は3〜4文まで
- 専門用語は初出時に説明
## 避けてほしいこと
- 「〜と言えるでしょう」のような曖昧な締め
- 過度な装飾や強調
## 触らないでほしいファイル
- `_templates/` 配下はテンプレートなので編集しない実験・プロトタイプ
## このプロジェクトについて
新しいライブラリの検証用プロジェクトです。
## 注意点
- コードの品質より動作確認が目的
- 本番投入は想定していない
- 大胆な変更を歓迎
## 検証したいこと
- ライブラリAとBのパフォーマンス比較
- エッジケースでの挙動確認今日から始める1行
CLAUDE.mdは、最初から完璧である必要はありません。
むしろ、最初から完璧を目指すと挫折します。
今日から始めるなら、「Claudeが勘違いしたこと」を1つだけ書き足してみてください。
次のセッションで同じ勘違いが起きなければ、それが成功体験になります。
その積み重ねが、やがてプロジェクト固有の知識ベースに育っていきます。
CLAUDE.mdは完成させるものではなく、育てるものです。
Claudeとの対話を通じて、プロジェクトの暗黙知を言語化していく。
その過程自体が、開発者としての思考を整理する機会にもなります。
参考になれば幸いです。
