前章までで、その場で文脈を渡す手段を見てきた。だが、毎回同じことを書きたくはない。「このプロジェクトはこういう作りで、こういう約束事がある」を一度書いておけば済むなら、それに越したことはない。

その役割を果たすのが CLAUDE.md である。

CLAUDE.md とは何か

CLAUDE.md はプロジェクトルートに置く特別なファイルで、Claude Code は会話を始めるたびにこれを読む。コードからは読み取れない約束事を伝える場所として機能する。

たとえばこんな内容を書く:

# Code style
- ES Modules (import/export) を使う。CommonJS (require) は使わない
- import は可能なら分割代入で書く

# Workflow
- 変更が一段落したら型チェックを実行する
- パフォーマンスのため、テストはまず個別実行を優先する

新しい会話を始めるたび、Claude はこれを最初に読み込む。その上で、こちらの指示に応じて動き出す。

何を書くか

書く価値があるのは、Claude が知りようのないことである。

  • Claude が推測できない bash コマンド (例: npm run typecheck、独自の起動スクリプト)
  • 言語の標準と違う、プロジェクト独自のコードスタイル
  • テストの走らせ方・推奨ランナー
  • ブランチ命名や PR の作法
  • 必須の環境変数、依存サービスなど開発環境の癖
  • よく踏む落とし穴・気づきにくい挙動

逆に書かなくてよいものは、Claude が自分で読めば分かることである。

  • コードを読めば判別できるアーキテクチャの説明
  • 言語の標準的な慣習 (Claude はすでに知っている)
  • 詳細な API リファレンス (公式ドキュメントへのリンクで十分)
  • 頻繁に変わる情報
  • 「きれいなコードを書け」のような自明な訓示

判断に迷ったら、こう問う: 「これを削ったら Claude は間違いを犯すか?」 答えがノーなら削ってよい。

最初の一枚を作る

ターミナル (もしくは VSCode 拡張) で /init を実行すると、Claude が現在のプロジェクト構造を分析して、土台となる CLAUDE.md を生成してくれる。

> /init

ビルドシステム、テストフレームワーク、コードパターンなどを拾って下書きを作るので、そこから自分の手で削ったり足したりして整えるのが手早い。

最初から完璧を目指す必要はない。短くてよい。Claude を使っていて「同じ説明を何度もしているな」と気づいたら、その都度 CLAUDE.md に足していく、くらいの育て方が現実的である。

短く保つ

CLAUDE.md は太りやすい。「念のため書いておこう」が積み重なると、本当に大事な指示がノイズに埋もれる。すると Claude は重要なルールを取りこぼし始める。

  • 何かを書き加える時は、本当に毎回必要かを問う
  • 定期的に読み返し、もう不要な行は削る
  • Claude が CLAUDE.md にあるルールを守らない時は、ファイルが長すぎて埋もれている可能性を疑う

CLAUDE.md はコードと同じで、保守する対象である。書き捨てではない。

このあと

CLAUDE.md の置き場所は、実はプロジェクトルート一つに限らない。ホームディレクトリ、親ディレクトリ、子ディレクトリと階層的に置けるし、@path/to/file で別ファイルをインポートする書き方もある。さらに進んで、用途別に分割した Skills という仕組みもある。

ただし、これらは応用の領域である。まずはプロジェクトルートに一枚、短く始めて育てる ─ 基礎としての CLAUDE.md はそこまでで十分機能する。

参考情報