CLAUDE.mdにルールを書いたのに、Claude Codeが平気で無視して同じミスを繰り返す——CLAUDE.mdの書き方でつまずくのは、たいてい「何を書くか」ではなく「どう書けば守られるか」を外しているからです。結論から言えば、守られるCLAUDE.mdは、コードを読めば分かることを書かず、禁止だけでなく代わりの行動を示し、200〜300行に絞り、繰り返し間違える箇所を名指しで釘刺しします。この記事では、CLAUDE.mdが守られない主な原因、指示を通すための書き方7つ、書くべき・書くべきでないことの一覧、プロジェクト規模別の分割、そしてサイト制作や自社ツール開発の現場で実際に使っているCLAUDE.mdの型まで、そのままコピーして直せる形でまとめます。
この記事の要点
- CLAUDE.mdが守られない原因の多くは「詰め込みすぎで薄まる」「禁止だけで代替行動が無い」「コードを読めば分かることを書いている」の3つです。行数を絞り、指示を具体化するだけで通り方が変わります。
- 指示を通す書き方は、①分かることは書かない ②禁止＋代替をセットにする ③200〜300行に収める ④繰り返す失敗をGotchasに名指しするなど7つ。コピペできる断片つきで示します。
- グローバル（
~/.claude/CLAUDE.md）・プロジェクト・ローカルの3階層を使い分け、タスク固有の指示をグローバルに置かないことが、規模が大きくなっても崩れない書き方の要点です。
01CLAUDE.mdとは｜Claude Codeが最初に読む設定ファイル
CLAUDE.mdは、Claude Codeがセッション開始時に読み込む、プロジェクトの取り扱い説明書です。新しく入ったメンバーに渡すオンボーディング資料に近く、「このプロジェクトではどう振る舞ってほしいか」をあらかじめ伝えておくためのファイルです。ここに書いた内容は毎回のやり取りの前提として読まれるため、うまく書けば指示の質が安定し、雑に書けば守られずに終わります。
CLAUDE.mdはどこに置くのか？
置き場所は主に3つあり、読み込まれる範囲が違います。全プロジェクト共通のルールはグローバル、その案件だけのルールはプロジェクト、自分の手元だけの設定はローカルに置くのが基本です。
| 置き場所 | パス | 読まれる範囲 |
|---|---|---|
| グローバル | ~/.claude/CLAUDE.md |
すべてのプロジェクトで常に読まれる |
| プロジェクト | リポジトリ直下のCLAUDE.md |
そのプロジェクトを開いたときだけ |
| ローカル | CLAUDE.local.md |
自分の環境だけ（共有しない） |
読み込みには順序と優先度がある
複数のCLAUDE.mdが同時に読まれると、内容が競合することがあります。原則として、より狭い範囲（プロジェクト・ローカル）の指示が、広い範囲（グローバル）より具体的な状況を上書きする前提で設計します。グローバルには全案件で崩したくない普遍ルールだけを置き、案件固有の判断はプロジェクト側に書き分けると、衝突が起きにくくなります。
02CLAUDE.mdが守られない・無視される主な原因
「書いたのに守ってくれない」の裏には、ほぼ決まった原因があります。編集部で複数のプロジェクトのCLAUDE.mdを運用して分かったのは、守られない理由の大半が内容ではなく書き方に集約されるという点です。まずは原因を切り分けます。
なぜ書いたルールが無視されるのか？
最大の原因は、情報を詰め込みすぎて一つひとつの指示が薄まることです。CLAUDE.mdはコンテキストの一部として読まれるため、行数が増えるほど個々のルールの存在感が下がり、結果的にどれも徹底されなくなります。次の3つが典型的な失敗です。
- 詰め込みすぎ：あれもこれもと書き、重要な数行が大量の一般論に埋もれる
- 禁止だけで代替が無い：「〜するな」とだけ書き、では何をすべきかが無いため行動に移せない
- 読めば分かることを書いている：ディレクトリ名や関数の中身など、コードを見れば分かる情報で行数を消費している
「一般論」はルールとして効力を持たない
「読みやすいコードを書く」「品質を意識する」といった一般論は、判断基準が無いため実際の挙動を変えません。ルールは、守れたかどうかを後から確認できる形（禁止語・数値・具体的な手順）まで落として初めて機能します。抽象的な心構えを並べるほど、CLAUDE.md全体の信頼度が下がっていきます。
03指示を通すCLAUDE.mdの書き方7つ
ここからは、実際に守られるCLAUDE.mdにするための書き方を7つ紹介します。共通しているのは「削って、具体化して、確認できる形にする」という方向です。
①コードを読めば分かることは書かない
ディレクトリ構成や関数の役割は、Claude Codeがコードを読めば把握できます。書くべきは、コードを読んでも分からないこと——プロジェクト固有のコマンド、意識的に選んだ制約、過去に繰り返し間違えられた箇所です。ここを外すと、限られた行数を「読めば分かる情報」で埋めてしまいます。
②禁止と「代わりにどうするか」をセットで書く
否定だけの制約は守りにくく、守れているかも分かりません。禁止するなら、必ず代替の行動を添えます。
否定だけ → 代替つきに直す
# 守られにくい
- console.logを残さない
# 守られやすい
- デバッグ出力はconsole.logではなくlogger.debug()を使う。
コミット前にlogger.debug呼び出しが残っていないかgrepで確認する③200〜300行に収める
行数の目安は200〜300行です。これを超えたら、増やすより削ることを先に考えます。長くなるほど個々の指示は薄まるため、行数はそのままルールの通り方に直結します。全案件で本当に守りたい数項目だけをグローバルに残し、あとは分割するのが安全です。
④繰り返し間違える箇所を名指しで釘刺しする
同じミスを何度も直させられた箇所は、CLAUDE.mdに「落とし穴（Gotchas）」として具体的に書き残します。「このプロジェクトでは日付を必ずJSTで扱う」「この関数は非同期なのでawait必須」のように、過去に実際に踏んだ地雷を名指しするほど再発が減ります。一般的な注意より、自分たちが踏んだ具体例のほうが効果があります。
⑤コマンドは主要な5〜7個に絞る
ビルド・テスト・リント・デプロイなど、そのプロジェクトで頻繁に使うコマンドを5〜7個だけ載せます。すべてのnpmスクリプトを列挙する必要はありません。よく使うものだけを正確に書くほうが、毎回の実行が安定します。
⑥タスク固有の指示をグローバルに置かない
「この案件のこの機能ではこうする」といった一時的・局所的な指示を~/.claude/CLAUDE.mdに書くと、無関係な全プロジェクトにまで影響します。タスク固有の指示はプロジェクトのCLAUDE.md、あるいは会話の中で直接渡すのが正解です。グローバルは「どの案件でも崩さない普遍ルール」だけにします。
⑦「どうやって正解を検証するか」を書く
作業の進め方そのものより、成果が正しいかをどう確かめるかを書くと、Claude Code自身が自己チェックしてくれます。「変更後はnpm testが通ることを確認」「文言を変えたら該当ページをスクリーンショットで確認」のように、検証手段を明示しておくと、指示待ちが減り手戻りも減ります。
04書くべきこと・書くべきでないこと【一覧表】
7つの書き方を、書く・書かないの軸で一覧にすると判断が速くなります。迷ったら「これはコードを読めば分かるか？」「守れたか後から確認できるか？」の2つで振り分けてください。
| 観点 | 書くべきでない（薄まる） | 書くべき（通る） | アウトプットの差（想定） |
|---|---|---|---|
| 構成の説明 | ディレクトリ名・関数の中身 | なぜその構成なのかの意図 | 読めば分かる情報で行数を消費しない |
| 制約 | 「〜するな」だけ | 禁止＋代わりの行動 | 行動に移せるので守られやすい |
| 品質 | 「読みやすく」「丁寧に」 | 禁止語・数値・確認手順 | 守れたか検証でき、挙動が変わる |
| コマンド | 全スクリプトの列挙 | 主要5〜7個だけ | 頻用コマンドの実行が安定する |
| スコープ | タスク固有をグローバルに | 普遍ルールだけグローバルに | 無関係な案件への誤爆が消える |
この表から分かるとおり、守られるかどうかは書く量ではなく、「後から守れたか確認できる形になっているか」で決まります。抽象的な心構えを10行足すより、確認できるルールを1行足すほうが、アウトプットは大きく変わると考えてよいです。Claude Codeの指示を安定させる考え方はDESIGN.mdでUIのAI感を消す型や、コンテキストを削減した実例とも共通します。
05プロジェクト規模が大きいときの分割方法
プロジェクトが大きくなると、200〜300行では収まりきらない場面が出てきます。そのときは1つのCLAUDE.mdを太らせるのではなく、分割とスコープ制御で対応します。
@importで役割ごとにファイルを分ける
CLAUDE.mdからは、別のマークダウンファイルを読み込ませることができます。コーディング規約・テスト方針・デプロイ手順などを別ファイルに切り出し、本体からは必要なものだけを参照する形にすると、本体を薄く保ったまま情報量を確保できます。全部を1ファイルに書くのではなく、「本体は目次と最重要ルール、詳細は別ファイル」という構成にします。
階層とスコープで「適用範囲」を限定する
モノレポのように複数のパッケージを抱える場合は、ディレクトリごとにCLAUDE.mdを置いて、その配下でだけ適用されるルールを分けます。フロントエンドとバックエンドで規約が違うなら、それぞれのディレクトリに置くほうが、全体に一律のルールを敷くより誤爆が減ります。3階層（グローバル／プロジェクト／ローカル）の使い分けは、先ほどの置き場所の表に沿って整理してください。
分割しても「本体から迷子にしない」
ファイルを分けたら、本体のCLAUDE.mdに「詳細は◯◯.mdを参照」と道筋を残します。分割そのものが目的ではなく、本体を薄く保ちつつ必要な情報にたどり着けるようにするのが狙いです。参照が切れた別ファイルは読まれず、書いた意味がなくなります。
06サイト制作・自社ツール開発でのCLAUDE.md【実践】
ここからは、編集部が実際にサイト制作と自社ツール開発で使っているCLAUDE.mdの型を、案件が特定されない汎用の形で紹介します。どちらも「繰り返し起きた失敗を釘刺しする」という発想で書いています。
LP・サイト制作用のCLAUDE.md断片
LP制作では、AIが生成しがちな装飾や、レスポンシブ崩れが繰り返しの失敗になります。そこを禁止＋代替＋確認手順の形で釘刺しします。
サイト制作プロジェクトの例（コピペ可）
## デザイン規約（毎回守る）
- 左borderカード・同系色パステル・絵文字アイコンは使わない。
代わりに白背景＋ヘアライン罫＋モノクロで組む
- 差し色は1色だけ。指定のhex以外を新規で足さない
- 文字色と背景が同系色になっていないか、書き出し前に必ず確認する
## 確認（納品前に必ず実行）
- レスポンシブ: 幅375 / 768 / 1280 の3幅でスクリーンショットを撮り崩れを確認
- 文言: 見出しと本文のコピーを実データで確認（ダミーのまま納品しない）ポイントは、抽象的な「きれいに作る」ではなく、過去に実際にやられた失敗（AI装飾・同系色・レスポンシブ崩れ）を名指ししていることです。確認手段まで書いておくと、Claude Code自身が書き出し前にチェックしてくれます。
自社ツール・自動化開発用のCLAUDE.md断片
スクレイピングやAPI連携、定期実行スクリプトの開発では、認証情報の扱いとデプロイ手順が繰り返しの事故ポイントになります。ここを固定します。
自社ツール開発プロジェクトの例（コピペ可）
## 認証情報（事故防止）
- APIキー・トークンをコードやJSONに直書きしない。
.envに置き、.gitignore済みであることをコミット前にgrepで確認する
- ログにキーを出力しない（set -xのまま鍵を扱わない）
## 実行・デプロイ手順
- ローカル検証: npm run dev で200を確認してからデプロイ
- 本番反映後は公開URLをcurlしてHTTP200と主要要素を検証する
- DBの破壊的操作（削除・スキーマ変更）は手順書に無い限り実行しない認証情報の直書き禁止は、実際に事故が起きやすい箇所です。CLAUDE.mdに「コミット前にgrepで確認」まで書いておくと、鍵の混入を仕組みで防げます。鍵の守り方そのものはClaudeの乗っ取り被害と認証情報の守り方でも詳しく整理しています。
07やりがちなアンチパターンと直し方
最後に、CLAUDE.mdでよく見かける失敗と、その直し方をまとめます。どれも「削る・具体化する」で解決します。
/initの出力をそのまま使う
/initで生成される雛形は出発点としては便利ですが、そのまま使うと「読めば分かる情報」が多く、肝心のルールが薄いままです。生成後に、コードを読めば分かる部分を削り、自分たちが繰り返し間違える箇所を書き足して初めて機能します。
リンターやフォーマッターの代わりにする
インデントや命令規則のような、ツールで自動化できる指摘をCLAUDE.mdに書くのは非効率です。整形はリンター・フォーマッターに任せ、CLAUDE.mdには「ツールでは表せない判断」だけを残します。
否定のルールだけを並べる
「〜するな」ばかりのCLAUDE.mdは、行動の指針が無いため守りにくくなります。前述のとおり、禁止には必ず代替行動を添えます。
すべてをグローバルに書く
便利だからと~/.claude/CLAUDE.mdに何でも書くと、無関係なプロジェクトにまでルールが漏れ出します。グローバルは普遍ルールだけにし、案件固有はプロジェクト側へ分けるのが鉄則です。
FAQよくある質問
CLAUDE.mdはグローバルとプロジェクトのどちらに書くべきですか？
全案件で崩したくない普遍ルールはグローバル（~/.claude/CLAUDE.md）、その案件だけのルールはプロジェクト直下のCLAUDE.mdに書きます。タスク固有の一時的な指示はグローバルに置かず、プロジェクト側か会話で直接渡してください。混ぜると無関係な案件へ誤爆します。
CLAUDE.mdは何行くらいが適切ですか？
目安は200〜300行です。超えたら足すより削るのを先に検討します。行数が増えるほど個々の指示が薄まり、結果的にどれも守られなくなるためです。詳細は別ファイルに切り出し、本体は薄く保ちます。
CLAUDE.mdが守られないときはどうすればいいですか？
まず行数を削り、禁止だけのルールに代替行動を足し、抽象的な心構えを確認できる形（禁止語・数値・手順）に直します。多くの場合、内容を追加するより、薄まっている原因を取り除くほうが効果があります。
CLAUDE.mdとAGENTS.mdは何が違いますか？
CLAUDE.mdはClaude Code向けの設定ファイルで、AGENTS.mdは複数のAIコーディングツールで共通に使うことを想定した記法です。両方を使う場合は、片方を実体、もう片方から参照させるなどして、内容の二重管理を避けると運用が楽になります。
CLAUDE.mdはどのくらいの頻度で更新すべきですか？
決まった頻度はありませんが、同じミスを二度直させたら、その場でCLAUDE.mdに追記するのが実務的です。逆に、しばらく守られている当たり前のルールや、もう使っていない指示は定期的に棚卸しして削ります。増やすだけでなく減らす運用が、ルールの効果を保ちます。
08まとめ：まず削ってから釘を刺す
CLAUDE.mdの書き方は、「何を足すか」よりも「何を削り、どこを具体化するか」で決まります。守られない原因の多くは詰め込みすぎと抽象化なので、まず200〜300行に絞り、読めば分かることを消し、残ったルールに代替行動と確認手順を添えるのが最短の直し方です。そのうえで、繰り返し踏んだ失敗を名指しで釘刺しし、タスク固有の指示はグローバルから追い出します。
次の一歩として、いま使っているCLAUDE.mdを開き、「これはコードを読めば分かるか？」で1行ずつ振り分けてみてください。半分近くが削れるはずです。UI周りの指示を安定させたい場合はDESIGN.mdの型、コンテキストを軽く保つ考え方はコンテキスト削減の実例も合わせて確認すると、CLAUDE.mdの設計がさらに固まります。
09出典
- Anthropic公式ドキュメント「Claude Code / Memory（CLAUDE.md）」
- Zenn farstep「効果的なCLAUDE.mdの書き方」
- FIXIT「CLAUDE.md のベストプラクティス — 書くべき8項目とテンプレート」