CLAUDE.mdは「何を書かないか」で決まる：粒度と更新の原則

CLAUDE.md に技術スタックも禁止事項もデプロイ手順もぜんぶ書いて、200行を超えた頃でした。Claude Code が、その200行の真ん中あたりに書いた「migrations は触るな」を、平気で無視したんです。

不思議でした。ちゃんと書いてあるのに。

理由は、あとで腑に落ちました。長い指示書は、人間でも全部は頭に残りません。AI も同じで、コンテキストが膨らむほど、一行一行の重みは薄まります。CLAUDE.md は「賢く書く」より「削って書く」ファイルだったんですね。今日は、僕が事故りながら掴んだCLAUDE.mdの原則を、何を書くか以上に「何を書かないか」と「いつ更新するか」に振って書きます。

なお、用途別にそのまま貼れるテンプレが欲しい人は、姉妹記事のCLAUDE.mdテンプレ集に7本まとめてあります。この記事はその裏側にある設計の原則のほうです。

この記事の要点

• CLAUDE.md の良し悪しは情報量ではなく粒度で決まる。長いほど良いは誤解で、重要な一行ほど薄まる。
• まず CLAUDE.md・Auto memory・settings・hooks の役割を分ける。禁止を本気で守らせたいなら CLAUDE.md ではなく permissions と hooks。
• 置くのは「毎回読む価値がある短い事実」だけ。コマンド、境界、検証手順は置く。議事録、過去ログ、秘密情報、今回だけの指示は置かない。
• CLAUDE.md は書いて終わりではなく運用ファイル。Claude Code が同じミスを2回したときだけ一行足す。
• 効果は「読ませた知識量」ではなく「減らせた確認往復の数」で測る。改善は足し算より引き算。

まず役割を分ける：CLAUDE.md・memory・settings・hooks

最初の事故の原因は、CLAUDE.md にぜんぶ背負わせたことでした。とくに「禁止」を CLAUDE.md だけに書いていたのが間違いです。

CLAUDE.md は、Claude Code に「こう振る舞ってほしい」と伝えるお願いです。お願いなので、文脈が混み合えば後回しにされます。本気で止めたい操作は、お願いではなく強制力のある仕組みに逃がす。ここを混同しないだけで、事故率がはっきり下がりました。

仕組み	性格	向いている内容
CLAUDE.md	人が書く永続的なお願い	規約、構成、検証コマンド、作業手順
Auto memory	Claude が保存するローカル学習	デバッグ知見、好み、繰り返す発見
settings / permissions	強制力のある許可リスト	許可・拒否、追加ディレクトリ
hooks	固定タイミングで走るコマンド	危険操作の停止、検証、自動整形

判断はシンプルです。「守られなかったら困るか?」で振り分ける。困らないなら CLAUDE.md。困るなら permissions か hooks。たとえば「force push するな」「本番 DB を触るな」は、CLAUDE.md に書くだけでは保険になりません。PreToolUse hook や deny ルールで物理的に止めて、CLAUDE.md には「なぜ止めているか」を一行添えるくらいがちょうどいい。権限とサンドボックスの分け方は権限設定ガイドで詳しく書いたので、本気で縛りたい人はそちらを。

読み込み場所と優先順位を運用視点で

CLAUDE.md は置き場所で挙動が変わります。ここを知らないと「書いたのに読まれない」が起きます。

Claude Code は、起動した作業ディレクトリから親方向に CLAUDE.md と CLAUDE.local.md をたどって読みます。サブディレクトリの CLAUDE.md は、その場所のファイルを読んだときに追加で効きます。つまり近いほうが強い。だから配置の原則はこうです。

• チーム全員で共有する内容はリポジトリ直下の CLAUDE.md。
• 自分だけのメモは CLAUDE.local.md（gitignore）。チームに押し付けない。
• パッケージ固有のお作法は、そのパッケージ直下に置いて近接させる。

repo/
  CLAUDE.md                 # チーム共有の永続ルール
  CLAUDE.local.md           # 個人メモ。gitignore する
  .claude/
    rules/
      api.md                # パス限定のルール
  packages/admin/CLAUDE.md  # このサブツリーを触ったとき効く

僕は最初、個人的な好み（「コミットメッセージは日本語で」みたいなやつ)を共有 CLAUDE.md に書いて、チームから「これ標準なの?」と突っ込まれました。好みは local、合意はルート。この線引きを最初に決めておくと、ファイルが荒れません。

置くもの・置かないものを線引きする

ここが本題です。CLAUDE.md に置くべきは、毎セッションで役に立つ、短い事実だけ。Claude Code は起動のたびに全文を読みます。毎回読む価値がない文章は、どれだけ正しくても常時メモリには向きません。

置くものと置かないものを、判断基準ごとに並べます。

判断	置く	置かない
コマンド	build / test / lint / typecheck / デプロイ前確認	一度しか使わないワンライナー
境界	変更してよい/触ってはいけないディレクトリ、命名規則	ディレクトリ構成の全列挙
手順	「API を触ったら該当 spec を回す」など順番	長い設計議論、過去の意思決定の全文
知識	判断に必要な公式 URL と基準	公式 docs の全文コピー
秘密	（置かない）	API キー、トークン、本番接続情報

ポイントは右列です。やりがちなのが、ディレクトリ構成をツリーで全部書くこと。気持ちはわかりますが、Claude Code はファイルを自分で探せます。必要なのは「どこを触っていいか」の境界であって、地図の丸写しではありません。地図はコンテキストを食うだけで、行動を変えません。

実際に効く CLAUDE.md の例を置いておきます。これくらい短くて十分です。コマンド・境界・手順・チェックの4ブロックだけ。

# Project Instructions

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Build: npm run build

## Change rules
- 既存パターンに沿った小さな差分を優先する
- auth・billing・migrations はタスクで明示されない限り触らない
- API ハンドラを直したら、同じ pass で validation とテストも更新する

## Review checklist
- コード・ログ・fixture・スクショに秘密情報を入れない
- happy path だけでなくエラー経路もテストする
- UI と公開文言で用語を揃える

## 最終応答の前に
- 実行したコマンドと、スキップした検証を報告する

この最後の「最終応答の前に」が、地味に一番効きます。「直しました」で終わらせず、何を回して何を飛ばしたかを毎回言わせる。これだけで「テスト回したフリ」が消えました。

粒度の原則：曖昧な指示を検証可能にする

「きれいに書いて」「いい感じに直して」——CLAUDE.md にこういう言葉を書いても、ほぼ効きません。人によって「きれい」の定義が違うのと同じで、AI も基準が取れないからです。

原則は一つで、検証可能な形に落とすこと。守れたかどうかをコマンドや具体名で判定できる粒度まで噛み砕きます。

• ×「きれいに書く」 → ○「npm run lint を通す」
• ×「適切に分割する」 → ○「default export は使わない」
• ×「テストを意識する」 → ○「src/api/** を触ったら該当 spec を回す」

僕は「環境変数は適切に扱う」と書いて、Claude Code が毎回 process.env を直読みするのを止められませんでした。「環境変数は src/config.ts 経由で参照する」と具体名で書いた瞬間、ピタッと直りました。粒度とは、抽象論をやめて固有名詞とコマンドで語ること、です。

育て方：CLAUDE.md は運用ファイル

最初から完璧な CLAUDE.md を書こうとすると、たいてい机上の理想論で埋まって、誰も守らないファイルになります。順番が逆なんです。

正しい順番はこう。まず既存プロジェクトで Claude Code に小さな修正を頼み、どこで迷ったか・どのファイルを余計に読んだか・どの検証を忘れたかを観察する。その結果だけを短いルールにする。観察から生まれたルールは守られます。理想から書いたルールは守られません。

更新のタイミングも絞ります。思いついたら足す、ではファイルが太ります。足すのは次の3つのときだけ。

1. Claude Code が同じミスを2回したとき（叱るのではなく一行足す）。
2. レビューで毎回同じ指摘が出るとき。
3. 新しいテストやデプロイのコマンドが増えたとき。

変更前には、秘密情報や腐ったルールが混ざっていないかを機械的に見ます。これはコピペで動きます。

# CLAUDE.md を変える前の30秒チェック
# 秘密情報・腐りかけワードが紛れていないか走査する
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules

# 直前の差分を確認してから commit する
git diff -- CLAUDE.md .claude/rules

行数の目安も持っておくと暴走しません。初期版は100行以内、育っても200行以内。200行を超えたら、削る → .claude/rules/ にパス限定で分ける → docs に逃がす → skill 化する、の順で整理します。冒頭の事故も、結局これで解決しました。200行を120行に削っただけで、「migrations は触るな」がまた効くようになったんです。

アンチパターン4つ：僕が踏んだ地雷

正直に、自分でやらかしたやつを共有します。

ひとつ目、会社 Wiki みたいに長く書く。説明が長いほど親切、という発想がそもそも間違いでした。読むのは人間ではなく AI で、長文の背景説明は重要な一行を薄めるだけ。マニュアルではなく運用ファイル、という前提を忘れると必ずこれをやります。

ふたつ目、README や議事録を @import で丸ごと読ませる。@docs/file.md の import は整理には便利ですが、読み込まれればコンテキストを消費します。トークン節約の手段ではありません。常時必要な5行だけを CLAUDE.md に残し、詳細は必要なときに読ませる。

みっつ目、コマンドだけ書いて手順を書かない。npm run test とだけ書くより、「billing を触ったら test を必ず回す」のほうが圧倒的に強い。コマンドは存在を伝えるだけ。手順は「いつ使うか」まで伝えます。

よっつ目、セキュリティの禁止を CLAUDE.md だけに書く。これが冒頭の事故の本質でした。Claude が従うとは限らないので、危険コマンドは permissions や PreToolUse hook で止める。CLAUDE.md はあくまでお願い、という性格を最後まで忘れないことです。

評価軸：減らせた確認往復で測る

最後に、僕が一番伝えたい原則を。実務で効く CLAUDE.md は、読ませた知識の量ではなく、減らせた確認往復の数で評価します。

• 毎回「どのテストを回しますか?」と聞かれる → コマンドと手順を足す。
• 毎回「このディレクトリ触っていいですか?」と迷う → 境界を書く。
• 誰も参照しない歴史説明がある → 消す。

この視点で見ると、改善は足し算より引き算のほうが効くとわかります。そして CLAUDE.md は人間にも読まれる前提で書く。Claude 専用の呪文にせず、新しく入った人が読んでもプロジェクトの作法が分かる文章にしておくと、AI 向け設定と人間向けオンボーディングを兼ねられて、更新する理由が増え、放置されにくくなります。

毎回のコンテキスト設計そのものをもっと知りたい人はコンテキスト管理の記事、Claude Code をこれから始める人は完全入門ガイドも合わせてどうぞ。

よくある質問

Q. CLAUDE.md は長いほうがいい? 短いほうがいい? A. 短いほうです。目安は初期100行、育っても200行以内。長いと重要な一行が薄まって守られにくくなります。長くなってきたら、それは .claude/rules/ や別 docs に切り出すサインです。

Q. 禁止事項を CLAUDE.md に書けば守ってくれますか? A. 守るとは限りません。CLAUDE.md は「お願い」なので、本気で止めたい操作は permissions の deny ルールや PreToolUse hook で物理的に止めてください。CLAUDE.md には「なぜ止めるか」を一行添える程度が役割分担として正解です。

Q. 日本語で書いても効きますか? A. 効きます。僕は禁止事項や手順を日本語で書くこともあります。海外メンバーと揃えるなら英語ベースが便利ですが、中身が検証可能な粒度になっていれば言語はどちらでも問題ありません。

Q. いつ更新すればいいですか? A. 「Claude Code が同じミスを2回した」「レビューで同じ指摘が繰り返される」「新しいコマンドが増えた」の3つのときだけです。思いついたら足す、をやるとファイルが太って逆効果になります。

Q. CLAUDE.md と Auto memory はどう使い分けますか? A. CLAUDE.md は人が書く永続的なお願い（規約・コマンド・境界）、Auto memory は Claude が自分で保存するローカルな学習（デバッグ知見や好み)です。人間が意図して共有したいルールは CLAUDE.md、自動で溜まる発見は memory、と覚えておけば混ざりません。

実際に試した結果

冒頭の「200行で migrations 事故」以来、僕は CLAUDE.md を太らせるのをやめました。代わりに、Claude Code が迷ったり同じミスをしたときだけ、一行ずつ足す運用に切り替えました。

効果は数字で出ました。src/config.ts 経由を明記しただけで環境変数の直読みはゼロに。「最終応答の前に実行したコマンドを報告する」を入れてからは、テストを飛ばしたままの「直しました」が消えました。逆に、ディレクトリツリーの丸写しや長い背景説明を削っても、出力の質は一切落ちませんでした。むしろ短くしたほうが、肝心の禁止事項が効くようになった。

結論はシンプルです。CLAUDE.md は、知識を盛るファイルではなく、確認往復を減らすファイル。何を書くかで悩む前に、何を消せるかを見たほうが速い、というのが今の実感です。まずは自分の CLAUDE.md を開いて、「これ毎回読む価値あるか?」を一行ずつ問い直すところから始めてみてください。

設計の原則を掴んだら、次は実物です。用途別のCLAUDE.mdテンプレ集から自分のリポジトリに一番近い1本を貼って、検証可能な Do Not を3行足してみてください。教材を一通り見たい方は教材一覧から、チーム標準化まで一緒に詰めたい方は研修・相談へどうぞ。

公式の一次情報は次を確認しました: memory, context window, settings, hooks。