CLAUDE.mdは書くほど逆効果になる — 200行の壁と4つの逃がし先

CLAUDE.mdは、Claude Codeがセッションの最初に必ず読み込む指示書です。丁寧に書き込んだCLAUDE.mdほど、かえって指示が守られなくなるという逆転が起きます。Anthropicの公式ドキュメントにもとづいて、書き方・中身・メンテナンス方法を整理しました。読めば、今のCLAUDE.mdを見直す具体的な基準が持てるようになります。

この記事の対象読者：Claude Codeを業務で使っている開発者、社内の生成AI活用ルールを整備したい情報システム担当、AIエージェント導入の判断を担う事業責任者の方

CLAUDE.mdとは何か — 置き場所と「命令ではない」という仕組み

CLAUDE.mdは、開発者が書き、Claudeがセッション開始時に読み込むマークダウンファイルです。置き場所は4つあり、スコープが異なります。

スコープ	置き場所	用途
組織全体	/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）	IT部門が配布する全社ルール
個人（全プロジェクト）	~/.claude/CLAUDE.md	自分の全プロジェクトに効く個人設定
プロジェクト	./CLAUDE.md または ./.claude/CLAUDE.md	gitに入れてチームで共有する
個人（このプロジェクトのみ）	./CLAUDE.local.md	個人の作業メモ。.gitignoreに入れる

これらは上書きではなくすべて連結されます。読み込む順番はスコープの広いものから狭いものへ、つまり組織全体・個人・プロジェクト・個人（このプロジェクトのみ）の順です。ここで注意したいのは、「後から読まれるファイルが優先される」というルールは存在しないことです。公式ドキュメントは「より具体的な指示が優先されるのが一般的」と書く一方、別の箇所では「2つのファイルが矛盾する場合、Claudeはどちらかを任意に選ぶ」とも書いています。優先順位に頼らず矛盾そのものを消す方法は、後半の「置き場所を分ける」節で扱います。

叩き台は/initコマンドで作成できます。Claudeがコードベースを解析し、ビルドコマンド・テスト方法・規約を検出したファイルを生成します。すでにCLAUDE.mdがある場合は上書きせず、改善案を提示します。外出先からClaude Codeを操作する運用まで含めて整えたい場合は、外出先でもClaude Codeを動かす方法を徹底比較もあわせて参考になります。

CLAUDE.mdは「命令」ではなく「文脈」です

CLAUDE.mdの内容は、システムプロンプトの一部としてではなく、システムプロンプトの後ろにユーザーメッセージとして流し込まれます。つまりClaudeにとっては「守るべき設定」ではなく「読んだ文脈」という扱いです。この仕組みを理解しておくと、CLAUDE.mdに何を書くべきかの判断が変わってきます。

書けば必ず守られるという保証はなく、曖昧な指示や他のファイルと矛盾した指示ほど効きにくくなります。必ず実行させたい処理は、CLAUDE.mdに書いてはいけません。ファイル編集のたびにLintを走らせる、特定のディレクトリへの書き込みを止めるといった「例外なく起きてほしいこと」はHooksに書きます。Hooksはライフサイクルイベントに対してシェルコマンドとして実行されるため、Claudeの判断に左右されません。

公式ドキュメントの表現を借りるなら、CLAUDE.mdに書いた「.envを絶対に編集しないこと」はお願いであり、PreToolUseフックでブロックするのが強制です。この区別を持たずに運用すると、「CLAUDE.mdに書いたのに守られない」という相談の大半が発生します。

長いCLAUDE.mdほど守られなくなる（200行の壁）

公式が示す目安は1ファイルあたり200行以内です。これを超えると文脈を余計に消費し、遵守率が下がります。やっかいなのは、この失敗が「サボった結果」ではなく「頑張った結果」として起きることです。

600行のCLAUDE.mdは、書いた人にとっては網羅的で親切なドキュメントに見えます。しかし重要なルールが些末な情報に薄められ、結果として全体の効きが落ちます。指示が守られないとき、1行足すのはたいてい逆効果です。むしろ削るほうが効きます。公式ドキュメントも「同じことを何度言っても守られないなら、ファイルが長すぎてそのルールが埋もれている可能性が高い」と説明しています。

何を書き、何を書かないか

公式ドキュメントは、書くものと書かないものに明確な線を引いています。迷ったときは「コードを読めば分かるか」で仕分けると判断が速くなります。

書くもの	書かないもの
Claudeが推測できないコマンド	コードを読めば分かること
自社固有のコードスタイル	その言語の標準的な作法
テストの実行方法・使うテストランナー	詳細なAPI仕様（リンクで足ります）
ブランチ名・PRの作法	頻繁に変わる情報
プロジェクト固有の設計判断	長い解説やチュートリアル
必須の環境変数など開発環境のクセ	ファイルごとの説明
非自明な落とし穴	「きれいなコードを書く」のような当然のこと

線引きに迷ったときの判定基準はひとつです。「この1行を消したら、Claudeは実際にミスをするか」と自問し、ノーなら削ります。この問いを全行に当てるだけで、たいていのCLAUDE.mdは半分になります。

同じ内容でも、書き方によって効き方が変わります。検証できる粒度まで具体的に書くことが重要です。「コードを整形すること」ではなく「インデントは2スペース」、「変更をテストすること」ではなく「コミット前にnpm testを実行する」のように書き換えます。守らせたい度合いが高い項目には「IMPORTANT」「YOU MUST」といった強調を足すと遵守率が上がりますが、全部に付けると強調が意味を失うため、本当に外せない数行に絞ります。

最初から作り込まない — 運用しながら育てる

CLAUDE.mdは、最初に完璧を目指すファイルではありません。公式ドキュメントは、追記のタイミングを4つ挙げています。

• 同じ間違いを2回した／Claudeが繰り返してしまった具体的な失敗があるとき
• レビューでの指摘／Claudeが知っておくべきだった内容がコードレビューで判明したとき
• 同じ修正指示の繰り返し／前回と同じ指示を、またチャットに打ち込んだとき
• 新メンバーへの説明／新しいメンバーにも同じ説明が必要になったとき

この4つはそのまま運用ルールになります。裏返せば、チャットで2回言ったことはCLAUDE.mdに書くという単純な習慣です。

同時に、剪定も定期的に回します。Claudeがその指示なしでも正しくできているなら、その行は削るかHooksに変換します。/doctorにはチェックイン済みのCLAUDE.mdの削減案を出す機能があり、ディレクトリ構成・依存パッケージ一覧・アーキテクチャ概要のようにコードから導けるものを削り、落とし穴・理由・ツール既定と異なる規約を残す方向で提案してくれます。コードと同じように扱うのが要点です。gitに入れ、レビューし、うまくいかないときに読み返し、定期的に刈り込むことで、CLAUDE.mdは時間とともに価値が増していきます。

膨らんできたら、4つの置き場所に振り分ける

200行を超えてきたときにやるべきことは、削るか、別の場所に逃がすかです。置き場所は4つあり、読み込まれるタイミングが異なります。

置き場所	読み込まれるタイミング	向いている内容
CLAUDE.md	毎セッション全文	全タスクに共通する前提
.claude/rules/	該当ファイルを読んだときだけ	言語・ディレクトリ固有のルール
Skills	呼び出されたとき・関連するとき	手順書・リファレンス
Hooks	文脈のコストはゼロ・確実に実行	必ず実行させたい処理

.claude/rules/の書き方も具体的に見ておきます。「APIエンドポイントには必ず入力バリデーションを入れる」というルールを、APIを触っているときだけ効かせたい場合は次のように書きます。

---
paths:
  - "src/api/**/*.ts"
---

## API開発のルール
- すべてのエンドポイントに入力バリデーションを入れます
- エラーレスポンスは標準フォーマットに従います

ファイル名は自由で、.claude/rules/以下の.mdは再帰的にすべて拾われます。こう書くと、Claudeがsrc/api/配下のファイルを読んだときにだけこのルールが文脈に入り、フロントエンドを触っている間はこの指示が1トークンも消費されません。pathsを書かなかったルールファイルは、CLAUDE.mdと同じく毎回読み込まれます。

ここで見落としやすいのが@pathによるimportです。CLAUDE.mdは@docs/git-instructions.mdのような記法で他のファイルを取り込めますが、取り込まれたファイルは起動時に全文が読み込まれます。ネストは4階層まで可能ですが、何階層に分けても文脈の消費量は変わりません。importは整理には役立っても軽量化にはならず、軽くしたいならpaths付きのルールかSkillに移す必要があります。外部サービスとの連携をSkillから呼び出す構成については、MCPとAPIは何が違うのかで仕組みを図解しています。

矛盾は、長さより厄介です

前述のとおり、複数のCLAUDE.mdが連結されても優先順位は保証されません。片方だけ直しても、もう片方に古い指示が残っていれば挙動は揺れ続けます。長すぎるCLAUDE.mdは効きが鈍るだけですが、矛盾したCLAUDE.mdは挙動そのものが読めなくなります。

対処は2つです。同じ話題を扱っているファイルを1つに統合するか、そもそも読み込ませないかのどちらかになります。モノレポで作業していると、親ディレクトリにある他チームのCLAUDE.mdが自動的に読み込まれ、自分たちのルールと衝突することがあります。他チームのファイルは統合できないため、この場合はclaudeMdExcludesで読み込み自体を止めます。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/Users/you/monorepo/other-team/.claude/rules/**"
  ]
}

プロジェクト直下の.claude/settings.local.jsonに置きます。settings.local.jsonはgit管理から外すのが慣例なので、チームに影響を与えずに自分の環境だけで効きます。値は除外したいファイルへの絶対パスに対するグロブパターンの配列で、ユーザー・プロジェクト・ローカル・組織全体のどの設定ファイルでも指定でき、配列は階層をまたいで結合されます。ただし組織全体のCLAUDE.mdだけは除外できません。

全社共通の指示を配布したい場合は、ファイルを置く代わりにマネージド設定へ直接書く方法もあります。managed-settings.jsonに{"claudeMd": "コミット前にmake lintを実行すること。"}と書けば、その内容がCLAUDE.mdとして全端末に効きます。これはマネージド設定でのみ有効で、個人やプロジェクトの設定に同じキーを書いても無視されます。

会話が要約されたあとの挙動にも差があります。プロジェクトルートのCLAUDE.mdはディスクから再読み込みされて復帰しますが、サブディレクトリのCLAUDE.mdとpaths付きのルールは自動では戻りません。該当するファイルを次に読んだときに再度読み込まれるため、「圧縮したら指示が効かなくなった」と感じたときは、たいていこれが原因です。

すべての組織に作り込みが必要なわけではありません

ここまでCLAUDE.mdの整備方法を解説してきましたが、整備が効くプロジェクトと、そうでないプロジェクトがあります。効きにくいのは標準的な構成の小規模プロジェクトです。よくあるフレームワークをそのまま使い、コマンドも慣例どおりで、触ってはいけない領域も特にない場合は、/initの出力に数行足した程度で十分で、それ以上書き込んでも遵守率を下げるだけです。

逆に投資対効果が高いのは、次のような組織です。

• 独自のビルド手順やツールチェーン／コマンドを推測できず、毎回説明が要る
• 触られると困る領域／生成物・ベンダーコードなど、変更されると事故になる箇所がある
• 社内用語とコードの乖離／社内用語とコード上の名前が一致していない
• 未文書化の落とし穴／過去に人間が踏んだ落とし穴が、ドキュメント化されずに残っている

つまり「新しく入った人に毎回説明していること」がある組織ほど効きます。その説明が存在しないなら、書くものはそれほどありません。CLAUDE.mdを充実させること自体を目的にしないよう気をつけたいところです。

複数のAIコーディングエージェントを併用していてAGENTS.mdを運用している場合も注意が必要です。Claude Codeが読むのはCLAUDE.mdであってAGENTS.mdではありません。二重管理を避けるには、CLAUDE.mdの先頭で@AGENTS.mdとimportして、その下にClaude Code固有の指示を書き足す形にします。CursorやWindsurfなど他のツールと併用している場合の比較は、AIコーディングツール徹底比較にまとめています。

よくある誤解と実際

CLAUDE.mdの運用で誤解されがちな点を整理しました。事前に知っておくと、遠回りせずに済みます。

誤解	実際	対処
詳しく書くほど守られる	200行を超えると遵守率が下がります	「消してもミスしないか」で毎行を判定します
プロジェクト側のCLAUDE.mdが常に優先される	確定的な優先順位はなく、Claudeの判断に委ねられます	矛盾を残さず、統合するか除外します
CLAUDE.mdに書けば必ず実行される	あくまで文脈であり、強制力のある設定ではありません	必須の処理はHooksやpermissions.denyに移します
@importで分割すれば文脈が軽くなる	importされたファイルは起動時に全文読み込まれます	軽量化したいならpaths付きルールかSkillに移します

まとめ — 運用を始める前に確認したい3つの問い

CLAUDE.mdの整備は、技術者の作業効率の話に見えて、実際には組織の資産化の話です。属人的な指示の出し方をgitに入るテキストファイルに変換すると、レビューでき、履歴が追え、新しいメンバーが読めるようになります。既存のCLAUDE.mdを見直すときも、これから書くときも、次の3つの問いが判断の軸になります。

• その1行を消したら、Claudeは実際にミスをするか／ノーなら削ります。網羅性は目的ではありません。
• それは毎回必要か、特定のファイルを触るときだけ必要か／毎回ならCLAUDE.md、特定のときだけならpaths付きのルールかSkillです。
• 守られなかったら困るのか／「守られたら嬉しい」ならCLAUDE.md、「守られないと事故になる」ならHooksです。

まずは/contextを実行して、自分のCLAUDE.mdが本当に読み込まれているかを確認するところから始めるのがおすすめです。そのうえで/doctorの削減提案を眺めると、書きすぎていた箇所が見えてきます。

参考リンク

• Best practices for Claude Code（Anthropic 公式）
• How Claude remembers your project（Anthropic 公式）
• Extend Claude Code（Anthropic 公式）

監修者

池田 智彦 ｜ 株式会社Spovisor 代表取締役

NTTドコモ・KDDIで通信業界に21年従事し、グローバル／国内市場で10以上の新規事業の立ち上げと、1,000万ユーザー規模サービスの開発・運用を主導。事業戦略から海外展開、エンジニアリングまで横断する経験を活かし、2023年6月に株式会社Spovisorを設立。現在はAI・アプリ開発、生成AIコンサル、AI駆動開発支援、AI顧問など、企業のDXを実装まで伴走する支援に取り組む。

Spovisor公式サイト ｜ お問い合わせ

生成AI／AIエージェントを「成果」に変える、Spovisorの伴走支援

株式会社Spovisorは、生成AI・AIエージェントを「使ってみた」で終わらせず、業務やプロダクトに組み込んで成果を出すところまで伴走する実装パートナーです。

支援領域	内容
生成AI組み込みアプリ開発	Claude／ChatGPT／AIエージェントを組み込んだ業務アプリや自社プロダクトの設計から実装まで支援
生成AI導入コンサル／AI顧問	経営課題や業務プロセスから導入ポイントを設計し、本番運用まで伴走
AI駆動開発支援	Claude Code／Codexを使った開発生産性向上を現場へ定着

無料相談・お問い合わせはこちら