Claude Code の CLAUDE.md には何を書くべきか
CLAUDE.md は、Claude Code がプロジェクトで作業を始めるたびに自動で読み込む、指示書のファイルです。リポジトリ直下に置いておくと、技術スタック・コマンド・規約・触ってはいけない場所などを、毎回の会話の最初から Claude が把握した状態で始められます。
雛形は /init で自動生成できます。ただし、生成されたまま放置すると、長くて当たり障りのない説明書になりがちです。CLAUDE.md は「置いてあれば効く」ものではなく、何を書くかで効きが大きく変わるファイルです。
この記事では、CLAUDE.md に何を書けば効き、何を書くと無駄（あるいは逆効果）になるのかを、実際に運用しているリポジトリの CLAUDE.md を例に整理します。CLAUDE.md の扱いはバージョン差の小さい機能ですが、本記事は Claude Code v2.1 系で確認しています。呼び出し口となるスラッシュコマンド側は、別記事 Claude Code のスラッシュコマンド 30 個 にまとめています。
CLAUDE.md とは何か、どこに置くか
CLAUDE.md は、置き場所によって読まれ方が変わります。
| 置き場所 | 役割 |
|---|---|
リポジトリ直下 CLAUDE.md | そのプロジェクト共通の指示。git に乗せて共有する |
~/.claude/CLAUDE.md | 全プロジェクト共通の、自分用の指示 |
サブディレクトリの CLAUDE.md | その階層で作業するときに追加で読まれる |
押さえておきたい前提が 1 つあります。CLAUDE.md は毎セッション読み込まれます。つまり、書いた内容はすべて、毎回の会話の文脈（トークン）を消費します。だから「長く詳しく書くほど良い」ではありません。短く、効くことだけを書く ── これが基本方針です。
書くと効くもの
経験上、CLAUDE.md で効果が大きいのは、次の 6 つです。
- プロジェクトの一行説明と技術スタック ── 「これは何で、何でできているか」。Claude の最初の前提になります。
- 主要コマンド ── ビルド・テスト・lint・開発サーバー・デプロイ。Claude が確認や検証をするたびに、探させないためです。
- ディレクトリ境界 ── どこに何があるか。どのディレクトリを触ってよく、どこは触らないか。
- 守ってほしい規約 ── 命名、既存パターンの踏襲、「新規ファイルより既存ファイルの編集を優先」など。判断に迷ったときの指針になることを書きます。
- やってはいけないこと ── 破壊的操作、復活させてはいけない撤退済みの仕組み、事実を捏造してはいけない領域。ここがいちばん効きます。
- デプロイと運用の注意 ── たとえば push が即デプロイになる構成なら、その事実と手順。事故の予防になります。
共通するのは、どれも「Claude が知らないこと」と「Claude に判断を任せたくないこと」だという点です。
書かない方がいいもの
逆に、書いても効かない（むしろ文脈を圧迫する）ものもあります。
- コードを読めば分かること ── 関数の一覧、ファイルの中身の逐語的な説明。Claude はコードを読めます。
- すぐ陳腐化する詳細 ── バージョン番号の羅列、進捗状況、「今やっていること」。これらは別のファイルに置きます。
- 一般的なベストプラクティス ──「テストを書く」「読みやすいコードを」。Claude はすでに知っています。
- 長い散文 ── CLAUDE.md は指示書であって、読み物ではありません。箇条書きで、断定形で書きます。
実例：このサイトのリポジトリの CLAUDE.md
抽象論だけだと掴みにくいので、実際に運用している例を挙げます。このサイト（novelarena.jp）のリポジトリの CLAUDE.md は、おおよそ次の構成です。
- 冒頭 ── このリポジトリが何か（一行）、技術スタック、本番 URL
- 「まずここを読む」── 作業前に目を通すべきファイルへのポインタ
- 「構成と運用」── ナビ構成、主要コマンド、このプロジェクト固有の仕組み
- 「デプロイ」── push で自動デプロイされること、ロールバックの手順
- 「触らない／してはいけない」── あるページは数値の捏造禁止、撤退済みの旧仕組みを復活させない、など
- 「ディレクトリ境界」── どのパスが何の役割か
実際にいちばん効いているのは、「触らない／してはいけない」と「ディレクトリ境界」です。Claude が良かれと思って撤退済みの仕組みを復活させたり、別プロジェクトのディレクトリに手を出したりする ── そういう善意の事故を、この 2 つが止めます。一般論はほとんど書いていません。書いてあるのは、このプロジェクトでしか通用しない固有の事情だけです。
更新のコツ
CLAUDE.md は、一度書いて終わりではなく、育てるファイルです。
/initで雛形を作り、そこから削る ── 生成直後がいちばん長い。要らない一般論を削る方向で整えます。- 同じ修正を 2〜3 回繰り返したら、書くサイン ── Claude に同じ指摘を繰り返しているなら、それは CLAUDE.md に書くべきルールです。
- 進捗や残タスクは別ファイルへ ──「今やっていること」は陳腐化が速い。CLAUDE.md には安定したことだけを置きます。
- 規約を変えたら CLAUDE.md も直す ── 現実とずれた古い CLAUDE.md は、ない方がマシなこともあります。
まとめ
CLAUDE.md がいちばん効くのは、Claude が「知らないこと」と「やってほしくないこと」を書いたときです。技術スタック、主要コマンド、ディレクトリ境界、禁止事項 ── まずはこの 4 つを、短く正確に。一般論と、コードを読めば分かることは省きます。/init で雛形を作り、そこから削る方向で、プロジェクトと一緒に育てていきましょう。
CLAUDE.md を生成する /init を含む、Claude Code 本体の組み込みスキルは、別記事 Claude Code の組み込みスキル 10 個 にまとめています。また、ここに書いた「毎回必要な前提」を会話で消さずに常駐させる話は、Claude Code のコンテキストを管理する で /compact・/clear の使い分けとあわせて掘り下げました。あわせて読むと、Claude Code の輪郭がいっそう掴みやすくなるはずです。