CLAUDE.md の書き方を調べていたら、正反対の主張に行き当たりました。
- A「20項目以上のテンプレートを用意して、役割・規約・テスト戦略・セキュリティまで網羅すべき」
- B「8行で十分。増やすより削るほうが効く」
どちらも自信を持って書かれています。両方試したうえで公式ドキュメントを読み直したところ、どちらが正しいかは明確に決着がつきました。しかも、単に「短くしよう」で終わらない理由がありました。
この記事では、なぜ長い CLAUDE.md が効かないのかを仕組みから説明し、実際に何を書くべきかまで整理します。
この記事の要点
- 公式の立場は「短く保つ」。肥大化すると本当に守らせたい指示が無視される
- 理由は2つ。毎リクエストのコンテキストに載ること、そして注意が希薄化すること
- 現行モデルでは、書くと逆効果になる指示がある。「検証しろ」「CRITICAL:」などは典型
CLAUDE.md とは何か
Claude Code がセッション開始時に自動で読み込む設定ファイルです。毎回同じ前置き（「日本語で」「箇条書きで」）を打つ手間を消せます。
置き場所は主に2つで、両方が読み込まれて合算されます。
| パス | スコープ |
|---|---|
~/.claude/CLAUDE.md |
全プロジェクト共通（自分専用） |
./CLAUDE.md（プロジェクト直下） |
その案件だけ。Git に入れればチーム共有 |
つまり 「自分の好み」は共通側に1回書けば全案件で効く、「その案件固有の前提」はプロジェクト側に書く、という分担ができます。
ゼロから書くのが面倒なら /init でたたき台が生成されます。/memory で編集できます。
CLAUDE.md は強制ではなくお願いです。公式も厳密な遵守は保証していません。外れたらその場で指摘して直す、という前提で使うものです。
二つの立場
立場A：網羅的に書く
役割、プロジェクト概要、コーディング規約、アンチパターン、記憶ファイル、エラーログ、コミット規約、テスト戦略、セキュリティ、ドキュメント、デプロイ、パフォーマンス、ログ、倫理、ツール、口調、思考プロセス……といった調子で、20項目以上のセクションを用意する考え方です。
主張の根拠は「AI に与える情報が多いほど、文脈を理解して精度が上がる」。直感的には筋が通っています。
立場B：最小限に留める
対して、10行以内に絞る考え方です。
# 私の設定
- 回答は必ず日本語で。
- 相手は非エンジニア。専門用語を使ったら、その場で1行でかみ砕く。
- 結論から先に。説明は箇条書き中心で、長い前置きは省く。
- 勝手にファイルを新しく作らない。既存のものを直す方を優先。
- 作業の前に、何をするつもりか1〜2行で先に教えて。
判断基準は明快です。「この行を消したら Claude がミスするか？ No なら消す」
検証：公式はどちらを支持しているか
公式は明確に立場B です。
Anthropic のベストプラクティスは CLAUDE.md を簡潔に保つことを推奨しています。そして重要なのは、単に「短い方が読みやすい」という話ではなく、肥大化すると本当に守らせたい指示が無視されるようになると警告している点です。
これは体感とも一致します。あれもこれも書いて50行になった結果、肝心の「日本語で」が埋もれて効かなくなる——という現象が起きます。
では、なぜそうなるのか。理由は2つあります。
理由1：CLAUDE.md は毎リクエストのコンテキストに載る
ここが見落とされがちです。CLAUDE.md はセッションの最初に1回読まれて終わりではありません。
Claude API はステートレスなので、会話を続けるには毎回すべての履歴を送り直す必要があります。CLAUDE.md はその先頭側に置かれるため、リクエストのたびに毎回送信されます。
つまり CLAUDE.md が長いほど、全リクエストのトークンコストが上がります。100回やり取りすれば100回分です。1回きりの初期化コストではありません。
さらに、プロンプトキャッシュの観点でも不利になります。キャッシュはプレフィックスの完全一致で効くため、CLAUDE.md を編集すると、それ以降のキャッシュが作り直しになると考えられます（Claude Code の内部実装は公開されていないので、ここは仕組みからの推測です）。
頻繁に変わる情報を CLAUDE.md に書くべきでない理由がこれです。
理由2：指示が増えると1つあたりの重みが下がる
より本質的なのはこちらです。
指示が5個なら、モデルはそれぞれに注意を払えます。指示が50個あると、個々の指示の相対的な重みが下がります。「日本語で」という一行が、「デプロイは CI/CD で自動化されています」という一行と同じ重みで並んでしまうわけです。
そして現行モデル（Claude Opus 4.5 以降）は指示に忠実になっています。これは一見メリットですが、裏返すと不要な指示の害も忠実に反映されるということです。
- 曖昧な指示 → 曖昧に解釈される
- 矛盾した指示 → どちらかを勝手に選ばれる
- 不要な指示 → 律儀に守られて無駄が生じる
モデルが賢くなったからこそ、書く内容を選ぶ必要があります。
検証：網羅テンプレートの中身を見る
ここが一番実害のある部分です。立場A のテンプレートには、現行モデルでは逆効果になる指示が混じっています。
「検証しろ」は削除するのが正解
網羅テンプレートには、たいてい「最後に検証ステップを入れる」「別のエージェントにレビューさせる」といった項目があります。
Claude Opus 5 は、言われなくても自己検証します。 そこに検証指示が残っていると、二重に検証して時間とトークンを消費します。
Anthropic の移行ガイドは、これを書き換えるのではなく削除するよう明示しています。削除しても品質は落ちません。
これは一般的なプロンプトのコツと逆になります。
「自己チェックさせると精度が上がる」は長く有効なテクニックでしたし、実際これまでのモデルではそうでした。Opus 5 では裏目に出ます。社内のプロンプト規約に「必ず自己検証の一文を入れる」と書いてあるなら、例外を切る必要があります。
「CRITICAL:」「MUST」は過剰反応を招く
「どうしても守らせたい行には IMPORTANT: を付けると遵守率が上がる」という話をよく見ます。これはやや古い推奨です。
Opus 4.5 以降のモデルは指示に忠実になったため、CRITICAL MUST If in doubt のような強い言葉は過剰反応（overtrigger）を招くと公式が明言しています。
| Before | After |
|---|---|
CRITICAL: You MUST use this tool when... |
Use this tool when... |
Default to using [tool] |
Use [tool] when it would improve X |
If in doubt, use [tool] |
（削除） |
ツールを使いすぎる、指示を過剰に適用する——といった症状が出たとき、追加のガードレールを書くのではなく、まず語気を弱めるのが正しい対処です。
「思考プロセスを開示しろ」は冗長化を招く
Opus 5 はもともと応答が長くなる傾向があります。そこに「段階的に思考を開示しろ」「複数の選択肢を比較検討しろ」と書くと、さらに伸びます。
判断できる場面では即座に着手させたほうが効率的です。
「もっと分担しろ」は世代で逆転している
サブエージェントへの委譲についても注意が必要です。Opus 4.8 は委譲が足りず促す必要がありましたが、Opus 5 は放っておいても自分から委譲します。4.8 向けに書いた「もっと委譲しろ」を残すと、必要以上に分担してコストと待ち時間が増えます。
現行モデルで効くのは、逆方向の指示です。
サブエージェントの起動は最大 3 体までとします。
結論：何を書くべきか
判断基準は立場B のものがそのまま使えます。
書く価値があるもの
モデルが推測できない情報だけです。
| 分類 | 例 |
|---|---|
| 言語・文体 | 「回答は必ず日本語で」 |
| 読み手の前提 | 「相手は非エンジニア。専門用語は1行で噛み砕く」 |
| 出力の形 | 「結論から先に。箇条書き中心」 |
| 禁止事項 | 「勝手にファイルを新規作成しない」「絵文字は使わない」 |
| プロジェクト固有の前提 | 技術スタック、命名規約、参照すべきドキュメントの場所 |
| スコープ規律 | 「指示された範囲だけ実施する」 |
最後の「スコープ規律」は現行モデルで特に効きます。Opus 5 は頼んでいないことまで気を利かせてやる傾向があるため、明示的に線を引くと止まります。
書かない方がよいもの
- 一般論 — 「丁寧に書いて」「保守性を重視して」。誰でも知っていることは枠の無駄
- モデルが放っておいてもやること — 「検証しろ」「テストを書け」
- 頻繁に変わる情報 — 進行中のタスク状況など。キャッシュを壊すうえに古くなる
- たまにしか使わない手順 — 毎回読まれて枠を食うので、別の仕組み（スキル等）に回す
- 曖昧な表現 — 「ちゃんとして」「自然に」。検証できない指示は効きません
増えてきたら分割する
内容が増えてきたら、CLAUDE.md の中に @ でパスを書くと別ファイルを読み込めます。
コーディング規約は @docs/coding-rules.md を参照。
1枚に詰め込むより整理しやすくなります。ただし読み込まれる総量は変わらないので、これは分量対策ではなく整理のための機能です。
運用のコツ
最初から完璧を目指さないことです。 3行から始めて、「あ、また同じ説明をした」と思ったら1行足す。この繰り返しで自分仕様になります。
守ってくれないときの切り分け順序はこうなります。
-
/memoryでそもそも読み込まれているか確認（パスが違うと読まれません） - 読まれているなら 長すぎ・曖昧・矛盾を疑う
- 定期的に棚卸しして、消せる行を消す
3番目が一番効きます。増やすより削るほうが効く、というのは体感でも公式の記述とも一致します。
まとめ
- 公式の立場は「短く保つ」。 肥大化すると本当に守らせたい指示が無視される
- 理由は毎リクエストのコンテキストに載ることと、指示が増えると1つあたりの重みが下がること
- 現行モデルには書くと逆効果になる指示がある。「検証しろ」は削除、「CRITICAL:」は語気を弱める、「もっと委譲しろ」は上限指定に置き換える
- 判断基準は 「この行を消したら Claude が実際にミスするか」
網羅的なテンプレートは、一見丁寧で安心感があります。でも CLAUDE.md は Claude を賢くする魔法ではなく、毎回の前置きを省くためのメモです。だから増やすほど効くのではなく、的を絞るほど効きます。
まずは自分の CLAUDE.md を開いて、消せる行を探してみてください。 たぶん、見つかると思います。