CLAUDE.mdが長すぎると逆効果？Claude Codeに守らせる指示の書き方

Claude Codeを使い込むと、CLAUDE.mdへルールを足したくなります。Claudeが一度ミスをするたびに「このファイルは変更しない」「必ずテストを実行する」「既存コードを確認する」「anyは使わない」「新しいライブラリを勝手に追加しない」「Git Commitは実行しない」と追記していくと、最初は数十行だったCLAUDE.mdが、数百行、場合によっては数千行になります。

しかし、CLAUDE.mdは長く書くほどClaudeが正確になるわけではありません。むしろ長すぎると、重要なルールが大量の説明に埋もれ、本当に守ってほしい指示を見落としやすくなります。Claude Codeの公式ドキュメントでも、1つのCLAUDE.mdは200行未満を目安にすること、長いファイルはContextを多く消費して指示への追従率が下がることが説明されています。

CLAUDE.mdで大事なのは情報量ではなく、Claudeが毎回知る必要のある重要な情報を、短く、具体的に、矛盾なく書くことです。この記事では、長すぎると逆効果になる理由と、守られやすい指示の書き方、他の仕組みへ移す基準を、公式ドキュメント（2026年10月時点）に沿って整理します。置き場所の選び方はClaude CodeのCLAUDE.mdはどこに置く？グローバル・プロジェクト別の使い分け、読み込まれないときの切り分けはClaude CodeがCLAUDE.mdを読まない原因｜配置場所・優先順位・読み込み範囲を確認で解説しているため、この記事は「何をどう書くか」に絞ります。

CLAUDE.mdは毎Session、Contextに読み込まれる
200行未満は「目安」であって上限ではない
長いと重要な指示が埋もれる
書くかどうかは「削除テスト」で決める
CLAUDE.mdに含める情報と、除外する情報
Claudeがコードを見れば分かることは書かない
一般論ではなく、このProjectとの「差分」を書く
曖昧な指示ではなく、検証できる指示を書く
理由を1文添える
禁止だけでなく、代わりの行動を書く
強調は、本当に重要な1行だけにする
指示同士を矛盾させない。同じルールを何度も書かない
見出しと短い箇条書きで整理する
ルールを追加するのは、同じミスが繰り返されたとき
追加する前に、既存のルールを具体的に書き換える
毎回は要らない情報は、別の仕組みへ移す
@Importで分割しても、Contextは減らない
「必ず守らせたい」ことは、CLAUDE.mdではなくHookとPermissionsに任せる
頻繁に変わる情報や、詳細なAPI仕様は入れない
/context、/doctorで確認・整理する
完成形は短くてよい
CLAUDE.mdの書き方に関するよくある質問
ルールを増やすより、ノイズを減らす

CLAUDE.mdは毎Session、Contextに読み込まれる

CLAUDE.mdは単なるProject Documentationではありません。Claude CodeはSession開始時にCLAUDE.mdをContextへ読み込みます。Project概要、Coding Rule、Testing Rule、Git運用、Architecture、注意事項が書かれていれば、それらがClaudeの作業時のContextになります。

したがって、1000行のCLAUDE.mdを書けば、その1000行を毎回読ませることになります。そのうち950行が今回の作業に関係なくても同じです。これはContextを消費するだけでなく、重要な50行を大量のNoiseの中へ埋もれさせる原因にもなります。

200行未満は「目安」であって上限ではない

公式ドキュメントでは、CLAUDE.mdは1ファイルあたり200行未満を目安にするとされています。長いファイルはContextを多く消費し、指示への追従率（Adherence）を下げるためです。

ただし、201行になった瞬間に効かなくなるという意味ではありません。200行はProtocol上の上限ではなく、運用上の目安です。50行でも冗長で矛盾した指示ばかりなら問題があります。逆に210行でも、すべてが重要で明確なら正常に機能する可能性があります。行数より大切なのは、この情報をClaudeが毎Session読む必要があるかという観点です。

長いと重要な指示が埋もれる

たとえば、本当に守らせたいルールが「Migrationファイルを変更してはいけない」だとします。CLAUDE.mdにProjectの歴史、Directory構成、Frameworkの説明、API一覧、Database仕様、Deployment手順、Coding Style、Test方法、Git Workflow、Troubleshootingが何百行も書かれていると、その中の1行の重要度は相対的に下がります。

Claude Codeの公式Best Practicesでも、禁止するルールを書いているのにClaudeが同じことを続けるなら、ファイルが長すぎてルールが埋もれている可能性が高い、と説明されています。守られないからといって、さらに10行説明を追加すると、逆効果になる可能性があります。

書くかどうかは「削除テスト」で決める

CLAUDE.mdを整理するとき便利なのが、公式Best Practicesが紹介している次の問いです。

削除テスト

この1行を削除したら、Claudeが実際にミスをする可能性が上がるか？

上がらない → 削る

たとえば「読みやすいコードを書いてください」は、ほぼ不要です。Claudeは通常、言われなくても読みやすいコードを書こうとします。一方、「既存APIのResponse Field名は変更しないでください。外部Clientとの互換性が必要です」は重要です。理由を知らなければ、ClaudeがRefactoringでField名を変える可能性があるからです。

CLAUDE.mdに含める情報と、除外する情報

公式Best Practicesは、含めるものと除外するものを次のように整理しています。

含める

Claudeが推測できないBash Command
デフォルトと異なるCode Styleのルール
Testの手順と、使うTest Runner
Repositoryの作法（Branch名、PRの規約など）
Project固有のArchitecture上の決定
開発環境の癖（必要な環境変数など）
一見して分からない注意点や挙動

除外する

コードを読めばClaudeが分かること
Claudeがすでに知っている標準的な言語の慣習
詳細なAPIドキュメント（ドキュメントへのリンクで十分）
頻繁に変わる情報
長い説明やチュートリアル
ファイルごとのコードベースの説明
「きれいなコードを書く」のような自明な指針

Claudeがコードを見れば分かることは書かない

たとえば「このProjectはReactを使っています」「src/componentsにComponentがあります」「package.jsonにDependencyが書かれています」は、Claudeが読めば確認できます。一方、次のような情報はSource Codeだけでは判断しにくいため、CLAUDE.mdに残す価値があります。

Source Codeから分からない情報の例

npmではなくpnpmを使用する

Legacy APIは互換性維持のため削除しない

Integration TestはDockerが必要なので、通常はUnit Testだけ実行する

一般論ではなく、このProjectとの「差分」を書く

ClaudeはTypeScript、React、Git、一般的なTesting Practiceについてすでに多くの知識を持っています。Reactとは何か、Unit Testとは何かを書く必要はありません。書くべきなのは、「一般的なProjectとこのProjectで何が違うか」です。

差分として書く

通常はnpmを使うこともある
  → このProjectはpnpm

通常はMigrationを変更できる
  → このProjectでは変更禁止

通常は全Testを実行できる
  → このProjectでは時間がかかるため対象Testのみ

曖昧な指示ではなく、検証できる指示を書く

「良いコードを書いてください」のような抽象的な指示は、あまり役立ちません。「良い」の基準が分からないからです。公式のmemoryページでも、次のように「検証できるほど具体的」に書くことが推奨されています。

「Format code properly」ではなく「Use 2-space indentation」
「Test your changes」ではなく「Run npm test before committing」
「Keep files organized」ではなく「API handlers live in src/api/handlers/」

たとえば次のような指示は、文章としては間違っていませんが、Claudeから見るとほとんどが一般論です。

NG: 一般論ばかりの指示

# Development

できるだけ良いコードを書いてください。

既存のコードを尊重してください。

必要に応じてテストしてください。

セキュリティに注意してください。

必要ならリファクタリングしてください。

どこまで変更してよいのか、何のテストを実行するのか、どのSecurity Ruleがあるのか、どの程度のRefactoringなら許可されるのかが分かりません。同じ内容でも、Project固有のルールへ変えます。

OK: Project固有で検証できる指示

# Development

既存の公開APIのField名とURLは変更しないでください。

新しいnpm packageを追加する前に、既存Dependencyで実装できないか確認してください。

TypeScriptを変更した後は、pnpm typecheckを実行してください。

src/migrations/以下のFileは変更しないでください。

大規模なRefactoringは、機能修正と同時に行わないでください。

理由を1文添える

短くすることは重要ですが、すべてを命令文だけにする必要はありません。「legacy-api.tsを変更しない」だけでは、Claudeが「古いFileだから削除してもよいのでは」と判断する可能性があります。「legacy-api.tsは外部Clientとの互換性維持に使われているため、削除・Renameしないでください」とすれば、Ruleの意図が伝わります。

ただし、100文字で説明できることを1000文字で説明する必要はありません。CLAUDE.mdは設計Documentではなく、作業時のInstructionです。

禁止だけでなく、代わりの行動を書く

「npmを使わない」だけでは、では何を使うのかが分かりません。「Package Managerにはpnpmを使用してください。npm installは実行しないでください」のように、禁止と代替行動をセットにします。同じように「Databaseへ直接Accessしない」だけでなく、「Database Accessはsrc/repositories/のRepository Layerを経由してください。Controllerから直接SQLを実行しないでください」とします。

Claudeが参考にするFileを示す書き方も有効です。公式Best Practicesでも、単に「Widgetを作る」と頼むより、既存の具体的なFileを例として示すほうが、必要な修正が減ると説明されています。CLAUDE.mdでも「参考にするFile」「使うCommand」「変更してよいDirectory」が分かるルールほど機能しやすくなります。

強調は、本当に重要な1行だけにする

CLAUDE.mdが肥大化すると、「必ず」「常に」「絶対」「IMPORTANT」「CRITICAL」「NEVER」だらけになることがあります。すべてを強調すると、何が本当に重要なのか分からなくなります。公式Best Practicesでも、Claudeが特定の1行を守らないなら、その行だけにIMPORTANTのような強調を付けられるが、多くの行を強調すると、どれも目立たなくなる、と説明されています。

強調は1行だけ

IMPORTANT: src/migrations/以下のFileは変更しないでください。Migrationが必要な場合は、変更せずに、理由をユーザーへ説明してください。

指示同士を矛盾させない。同じルールを何度も書かない

Claudeがルールを守らない原因が、長さではなく矛盾であることもあります。たとえばGlobalのCLAUDE.mdに「変更後は必ず全Test Suiteを実行してください」、ProjectのCLAUDE.mdに「変更後は対象Testだけを実行してください。全Test Suiteは実行しないでください」と書かれているケースです。Claude Codeでは複数のCLAUDE.mdやRuleが上書きされずにContextへまとめて読み込まれるため、Instructionが衝突するとClaudeがどちらかを任意に選ぶ可能性があると、公式でも説明されています。User、Project、サブディレクトリのCLAUDE.md、.claude/rules/を定期的に見直します。

また、Claudeに守らせたいからといって、同じルールをGlobal、Project、.claude/rules/、CLAUDE.local.mdのすべてに書く必要はありません。あるFileでは「Migration変更禁止」なのに、別のFileだけ古い「必要ならMigrationを修正」が残る、といった食い違いの原因になります。Ruleは適切なScopeへ1回だけ書きます。

見出しと短い箇条書きで整理する

公式のmemoryページでは、関連する指示をMarkdownの見出しと箇条書きでまとめると、密集した文章よりClaudeが追従しやすいと説明されています。

見出しで役割を分ける

# Commands

Package Managerにはpnpmを使用してください。

TypeScript変更後はpnpm typecheckを実行してください。

# Architecture

Database Accessはsrc/repositories/を経由してください。

Controllerから直接SQLを実行しないでください。

# Safety

src/migrations/以下は変更しないでください。

Dependency追加前に理由を説明してください。

ルールを追加するのは、同じミスが繰り返されたとき

では、どのタイミングで新しいルールを追加するべきでしょうか。公式のmemoryページでは、次のような場合が目安として挙げられています。

Claudeが同じミスを2回したとき
Code Reviewで「このCodebaseならClaudeが知っておくべきだった」と指摘されたとき
前回のSessionと同じ訂正や補足を、チャットで入力しているとき
新しく参加したメンバーが、生産的になるために同じ前提知識を必要とするとき

1回だけ起きた特殊なケースをすべて追加していくと、すぐ肥大化します。繰り返し起きる問題かどうかを見てから追加しましょう。

追加する前に、既存のルールを具体的に書き換える

たとえばClaudeがTestを実行しなかったとき、既存のCLAUDE.mdに「変更後は適切にテストしてください」とあるなら、「必ずテストしてください。重要です。忘れないでください」と3行足す必要はありません。元の1行を「TypeScriptを変更した場合は、完了前にpnpm testとpnpm typecheckを実行してください」に書き換えます。Ruleを増やすより、既存Ruleを具体的にするほうが、CLAUDE.mdを短く保てます。

毎回は要らない情報は、別の仕組みへ移す

CLAUDE.mdを短くするのは、必要な情報を捨てることではなく、役割を分けることです。移し先の基準は次のとおりです。

特定のDirectoryやFile種類だけのルール：pathsを指定した.claude/rules/へ。該当するFileをClaudeがRead・Write・Editしたときに読み込まれるため、不要なInstructionを常時Contextへ入れずに済みます（Claude Code settings.json完全リファレンス｜全フィールドの意味と.claude/rules/の使い方）
特定のTaskだけの長い手順（Release、Issue対応、Security Reviewなど）：.claude/skills/のSkillへ。公式Best Practicesでも、いつも必要ではないDomain Knowledgeやワークフローは、Claudeが必要なときに読み込むSkillを使うよう案内されています
必ず実行・禁止したい処理：HookやPermissionsへ（次の節）
詳細なDocumentation：Documentationとして残し、必要なTaskでClaudeに読ませる

たとえばRelease手順は、CLAUDE.mdには「Release作業にはreleaseスキルを使用してください」とだけ書き、手順の本体は.claude/skills/release/SKILL.mdに置けば足ります。

@Importで分割しても、Contextは減らない

長いCLAUDE.mdを整理するため、@docs/coding-rules.mdのようにImportする方法があります。Fileの整理には有効ですが、Context削減にはなりません。Importされたファイルも、CLAUDE.mdと一緒にSession開始時にContextへ読み込まれるためです。公式ドキュメントでも、Importは整理には役立つがContextのコストは減らないと明記されています。1000行のCLAUDE.mdを、100行のCLAUDE.mdと900行のImportファイルに変えても、読み込む量はほぼ変わりません。

参照先を示すだけで毎回の全文読み込みを避けたいときは、@を付けず、Backtickでdocs/api.mdのように書きます。Backtick内の@pathや、Code Block内の@pathはImportされません。

「必ず守らせたい」ことは、CLAUDE.mdではなくHookとPermissionsに任せる

CLAUDE.mdに「Fileを変更したら必ずeslintを実行してください」と書いても、CLAUDE.mdはContextとして読まれる指示で、強制ではありません。公式Best Practicesでは、CLAUDE.mdの指示は助言（advisory）であり、Hookは決定的に動作して、その処理が必ず起きることを保証する、と説明されています。例外なく毎回実行させたい処理にはHookを使います。CLAUDE.mdに「絶対に変更しないでください」と10回書くより、PreToolUse Hookで実際に拒否するほうが確実です。Hookの作り方はClaude Code Hooks完全ガイド｜Command・HTTP・Prompt・Agentフックの設定と実践活用で解説しています。

たとえば、次のように「ClaudeにHookを書いてもらう」使い方も、公式Best Practicesで紹介されています。

Claudeへの依頼の例

Write a hook that runs eslint after every file edit

Write a hook that blocks writes to the migrations folder

また、「.envを絶対に読まないでください」とCLAUDE.mdに書いても、それをSecurity Boundaryにしてはいけません。読ませたくないFileは、Permissionsのdenyルールで拒否します。

.claude/settings.json

{
  "permissions": {
    "deny": [
      "Read(./.env)"
    ]
  }
}

整理すると、「できるだけ守ってほしいProject Rule」はCLAUDE.md、「絶対に実行してはいけないOperation」はPermissionsやHook、という分離になります。

頻繁に変わる情報や、詳細なAPI仕様は入れない

「現在のVersionは1.8.4」「今週はFeature Aを優先」「現在のProduction Serverはxxx」のような頻繁に変わる情報を入れると、すぐ古くなります。古いInstructionは、何も書いていない状態より危険な場合があります。公式Best Practicesでも、頻繁に変化する情報はCLAUDE.mdから除外するよう案内されています。一時的なTaskの要件は、そのSessionのPromptで指定します。

API仕様をClaudeに把握させたいからと、数百行のEndpoint一覧をCLAUDE.mdへ貼る必要もありません。必要なTaskでDocumentationを読ませればよいので、CLAUDE.mdには「API仕様はdocs/api.mdを参照」程度を書きます。

/context、/doctorで確認・整理する

Claudeがルールを守らないとき、書き方より前に、CLAUDE.md自体が読み込まれていない可能性もあります。/contextを実行すると、Memory filesの一覧から、どのCLAUDE.mdやRuleが読み込まれているかを確認できます。

整理には/doctorが使えます。公式Best Practicesによると、Gitにコミットされている（checked-inの）CLAUDE.mdに対して/doctorを実行すると、コードベースからClaudeが導ける内容を、削る提案として出してくれます。さらにClaude Code v2.1.283以降では、/doctor prompt-auditが追加されました。CLAUDE.md、CLAUDE.local.md、AGENTS.md、.claude/以下のRuleやSkillなどを調べ、古いModel向けに書かれた指示、存在しないFileやCommandへの参照、互いに矛盾するFileを見つけて、修正案のレポートを出します。Claudeが適用を求められるまでは、Fileは変更されません。数か月運用して肥大化したCLAUDE.mdの、定期的なCleanupに使えます。

完成形は短くてよい

たとえばWeb Applicationなら、Project CLAUDE.mdは次の程度でも十分な場合があります。

CLAUDE.md（数十行の完成形）

# Commands

Package Managerにはpnpmを使用してください。

TypeScript変更後はpnpm typecheckを実行してください。

変更した機能に対応するTestを実行してください。

# Architecture

API Handlerはsrc/api/handlers/に配置してください。

Database Accessはsrc/repositories/を経由してください。

既存の公開APIのURLとResponse Field名は変更しないでください。

# Dependencies

新しいPackageを追加する前に、既存Dependencyで実装できないか確認してください。

# Safety

IMPORTANT: src/migrations/以下のFileを変更しないでください。Migrationが必要な場合は、ユーザーへ説明してください。

数十行しかありませんが、使うCommand、Architecture、互換性、Dependency方針、変更禁止の範囲という、Claudeが自力では判断しにくい情報が入っています。何百行ものProject Manualより、こうした短いルールのほうが、実際のCoding Sessionでは役立つことがあります。なお、設計の考え方はClaude Code CLAUDE.md完全設計ガイド｜3層構造・@インポート・自動メモリでAIとのコンテキスト共有を最大化も参考にしてください。

CLAUDE.mdの書き方に関するよくある質問

QCLAUDE.mdは何行までなら大丈夫ですか？

A公式ドキュメントでは、1つのCLAUDE.mdを200行未満にすることが目安とされています。ただし厳密な上限ではなく、行数より「毎Session必要な情報か」「Claudeがコードから分かることではないか」「他のルールと矛盾していないか」を基準にします。

Qルールを守ってくれないので、「絶対」「必ず」を増やしてもよいですか？

A1行だけにIMPORTANTのような強調を付けるのは有効ですが、多くの行を強調すると、どれも目立たなくなると公式でも説明されています。守られない原因は、ファイルが長すぎてルールが埋もれているか、ルールが曖昧か、他のルールと矛盾していることが多いため、まず削除テストで整理します。

Q長いCLAUDE.mdを複数ファイルに分けて@でImportすれば、Contextは減りますか？

A減りません。Importされたファイルも起動時にContextへ読み込まれるため、整理には役立ちますが、Contextの消費は変わりません。Contextを減らしたいなら、paths付きの.claude/rules/やSkillへ移します。

Q「.envを読まない」とCLAUDE.mdに書けば十分ですか？

A十分ではありません。CLAUDE.mdは強制される設定ではなく、Contextとして読まれる指示です。確実に拒否したいなら、Permissionsのdenyルール（Read(./.env)など）やPreToolUse Hookを使います。

Q古くなった指示を、まとめて見つける方法はありますか？

AClaude Code v2.1.283以降なら、/doctor prompt-auditで、CLAUDE.md・Rule・Skillなどから、古いModel向けの指示、存在しないFileやCommandへの参照、矛盾するFileを調べ、修正案のレポートを出せます。Claudeに適用を求めるまで、Fileは変更されません。

ルールを増やすより、ノイズを減らす

Claude Codeが指示を守らないと、「もっと詳しく書こう」「もっと強く書こう」「同じルールを何度も書こう」と考えがちです。しかし公式Best Practicesはむしろ逆で、CLAUDE.mdを短く保ち、不要な行を積極的に削ることを勧めています。目安は1つのCLAUDE.mdを200行未満にすることです。

ただし本当に見るべきなのは行数ではありません。「このルールは毎Session必要か」「Claudeがコードを読めば分かることではないか」「検証できるほど具体的か」「他のルールと矛盾していないか」を基準にします。Claudeが繰り返し間違える重要事項はCLAUDE.mdに残し、特定のDirectoryだけのルールは.claude/rules/、特定のTaskだけの手順はSkill、絶対に守らせたい制限はHookやPermissionsへ分けます。

CLAUDE.mdはProjectのすべてをClaudeへ教える百科事典ではありません。Claudeが作業するたびに忘れてほしくない、少数の重要事項だけを置くファイルとして設計するほうが、結果的に指示を守らせやすくなります。