
やりがちなCLAUDE.mdの失敗パターン|#3
この記事を読むとどんな悩みが解決するか
CLAUDE.mdを書いたのに、Claude Codeの挙動が全然変わらない
/init で自動生成したものをそのまま使っているが問題ないか不安
書けば書くほど効果が薄くなっている気がする
チームのCLAUDE.mdが膨らみ続けていてどう整理すればいいか分からない
この記事を読むと「なぜ効果が出ないのか」の原因が特定でき、今すぐ直せる。

第2回でCLAUDE.mdの設計論を学んでも、実際に書くと陥りやすいミスがある。5つの失敗パターンはそれぞれ独立した問題ではなく、1つを直すと別の問題も連鎖して解決していく構造になっている。
失敗パターン1:Wikiダンプ
症状:プロジェクトに関するあらゆる情報をCLAUDE.mdに詰め込む。
## プロジェクト概要
このプロジェクトは2024年4月に開始した、ECサイトのリニューアル案件です。
クライアントはXX株式会社で、月間PVは約100万、ユーザー数は...(以下延々と続く)
## 使用技術
Node.jsはv20.x系を使用しています。npmはv10以上が必要です。
TypeScriptのバージョンは5.3で、tsconfig.jsonのtargetはES2022に...
なぜ失敗か:
Claude Codeはファイルを読める。package.json・tsconfig.json・README.mdを直接参照できるので、そこに書いてある情報をCLAUDE.mdに転記しても意味がない。
むしろ害がある。CLAUDE.mdが長くなるとコンテキストを圧迫し、本当に重要なルールが埋もれる。2,000トークンという推奨上限(第2回参照)はこのためにある。
直し方:
「Claude Codeがファイルを読めば自明にわかること」は全部削除する。CLAUDE.mdに残すのは、ファイルを読んでも分からない判断基準・方針・禁止事項だけだ。
この章の相互作用と実践アクション
Wikiダンプを直すと、必然的に「何が本当に重要か」を選別することになる。この選別の作業が、次のパターン2(/initの罠)とパターン3(曖昧なルール)を直すきっかけになる。不要な情報を削ったあとに残るのが「本当に書くべき内容」だからだ。
今すぐできること:
Claude Codeにこう伝える:
CLAUDE.mdを開いて、package.json・tsconfig.json・README.mdを読めば
分かる情報をすべてリストアップして。削除候補として提示してほしい。
提示されたリストを確認して、不要な情報を削除する。
失敗パターン2:/initの自動生成をそのまま使う
症状:/init を実行して生成されたCLAUDE.mdをそのまま使い続ける。
/init が生成するCLAUDE.mdの典型例:
# Project Overview
This is a Next.js project using TypeScript and Tailwind CSS.
## Tech Stack
- Next.js 14.2.0
- React 18.3.0
- TypeScript 5.3.3
- Tailwind CSS 3.4.0
## Scripts
- `npm run dev`: Start development server
- `npm run build`: Build for production
- `npm run test`: Run tests
なぜ失敗か:
package.jsonを見れば全部わかる情報しか書かれていない。Claude Codeにとって新しい情報がゼロだ。コンテキストを消費するだけで、挙動改善には何も貢献しない。
これはパターン1(Wikiダンプ)の自動生成版だ。手動で詰め込むか、ツールに詰め込ませるかの違いだけで、問題の本質は同じ。
直し方:
/init はあくまでファイルを生成するだけのコマンドだと理解する。生成後に内容を確認して、自明な情報はすべて削除する。残すのは自分が意図的に書き加えた内容だけ。
最終的にCLAUDE.mdがほぼ空になっても構わない。「書くことがない=プロジェクトの制約が少ない」ということで、それは正常な状態だ。
この章の相互作用と実践アクション
パターン1でWikiダンプを削除した後、/initの自動生成も削除すると、CLAUDE.mdにはほぼ何も残らない。それが正しいスタート地点だ。
空になったCLAUDE.mdに、次のパターン3で学ぶ「具体的なルール」を自分の手で書き加えていく。削除と追加のサイクルが、精度の高いCLAUDE.mdを育てる。
今すぐできること:
Claude Codeにこう伝える:
CLAUDE.md を確認して、/init で自動生成されたと思われる内容
(バージョン番号・スクリプト一覧・プロジェクト概要)を
すべて削除候補としてリストアップして。
失敗パターン3:曖昧なルールを書く
症状:良かれと思って抽象的なルールを書く。
## コーディング規約
- コードはきれいに書いてください
- 適切なエラーハンドリングを心がけてください
- パフォーマンスに配慮してください
なぜ失敗か:
「きれいに」「適切に」「配慮して」は判断基準がない。Claude Codeは確率的に動くシステムで、曖昧な指示は解釈がブレる。
数字で見ると明確だ。
具体的なルール → 遵守率 89%
曖昧なルール → 遵守率 35%
同じルールでも書き方次第で遵守率が2倍以上変わる。
直し方:
抽象的なルールを具体的な禁止事項・条件に書き直す。
## 禁止事項
- `any` 型の使用禁止(`unknown` を使うこと)
- try-catchなしの非同期処理禁止
- レンダリングごとに新しいオブジェクトを生成する書き方禁止
「何をしてはいけないか」を具体的に書くのが最も効果的だ。
この章の相互作用と実践アクション
パターン1・2で不要な情報を削除し、ここで初めて「何を書くべきか」の答えが見えてくる。削って残ったスペースに、具体的な禁止事項を書き加える。
この「削る→具体的に書く」の流れが、第2回のWHATルール(89%遵守)を実現する実践的な手順だ。
また、ここで書いた具体的な禁止事項は次のパターン4(更新しない)と直結する。禁止事項は一度書いて終わりではなく、Claude Codeが間違えるたびに追加していくものだ。
今すぐできること:
現在のCLAUDE.mdを開いて、「きれいに」「適切に」「心がけて」などの抽象表現を探す。
Claude Codeにこう伝える:
CLAUDE.mdの中で曖昧な表現(「きれいに」「適切に」「配慮して」など)を
すべて見つけて、具体的な禁止事項に書き直す案を提示して。
失敗パターン4:一度書いたら更新しない
症状:最初にCLAUDE.mdを書いて、そのまま放置する。
なぜ失敗か:
Claude Codeが同じミスを繰り返しているのに、CLAUDE.mdに追記しないのは機会損失だ。同じ指摘を毎回プロンプトで伝えるのは非効率で、セッションをまたいだら引き継がれない。
直し方:
「また同じミスをした」と感じた瞬間がCLAUDE.mdに追記するタイミングだ。
運用サイクルはシンプル:
Claude Codeが間違えた
↓
なぜ間違えたかを考える
↓
CLAUDE.mdに具体的な禁止事項を追記
↓
同じミスが減る
CLAUDE.mdは完成させるものではなく、育てていくドキュメントだ。
この章の相互作用と実践アクション
パターン3で「具体的に書く」習慣ができると、このサイクルが自然に回り始める。「また同じミスをした → 禁止事項に追記する」という反射が身につく。
ただし追記し続けると今度はパターン5(1ファイルに集約)に陥る。追記するたびに「これはプロジェクト全体のルールか、特定のディレクトリだけのルールか」を意識する習慣をセットで持つと良い。
今すぐできること:
開発セッション終了時にClaude Codeにこう伝える:
今日のセッションで私が修正を指示した箇所を振り返って、
CLAUDE.mdに追記すべき禁止事項を提案して。
失敗パターン5:すべてをルートのCLAUDE.mdに書く
症状:プロジェクトが大きくなっても、CLAUDE.mdが1ファイルのまま膨らんでいく。
なぜ失敗か:
フロントエンドのルールもバックエンドのルールもDBのルールも全部混在すると、どのルールがどの文脈で適用されるか不明確になる。Claude Codeが参照するコンテキストも不必要に大きくなる。
直し方:
第2回で解説したカスケード構造を使う。特定のディレクトリにしか適用しないルールは .claude/rules/ に分割する。
.claude/rules/
├── frontend.md # /app 配下のルール
├── api.md # /app/api 配下のルール
└── database.md # /lib/supabase 配下のルール
ルートの CLAUDE.md はプロジェクト全体に適用する最小限のルールだけ残す。
この章の相互作用と実践アクション
5つのパターンの集大成がここだ。パターン1〜4を通じて「削る・具体化・更新する」を繰り返すと、CLAUDE.mdが肥大化してくる。その肥大化を防ぐ仕組みがカスケード構造だ。
「このルールはどのディレクトリにだけ適用したいか」という問いが、自然とCLAUDE.mdを分割する動機になる。分割することで2,000トークンの上限も守りやすくなる。
今すぐできること:
Claude Codeにこう伝える:
現在のCLAUDE.mdを確認して、特定のディレクトリ(フロントエンド・API・DBなど)
にしか適用しないルールを見つけて。
.claude/rules/ に分割する案を提示してほしい。
まとめ
▼ Wikiダンプ
問題:コンテキスト圧迫・重要ルールが埋もれる
対処:自明な情報をすべて削除する
▼ /init そのまま使用
問題:有用な情報ゼロ
対処:生成後に中身を精査・削除する
▼ 曖昧なルール
問題:遵守率35%に低下
対処:具体的な禁止事項に書き直す
▼ 更新しない
問題:同じミスが繰り返される
対処:間違えるたびに追記する
▼ 1ファイルに集約
問題:肥大化・文脈が混在
対処:カスケード構造で分割する
実践1:CLAUDE.md一括診断プロンプト
5つの失敗パターンをまとめて診断できる。Claude chatに以下をそのまま貼り付ける:
あなたはCLAUDE.mdの診断医です。
以下の5つの失敗パターンをチェックして、問題点と修正案を提示してください。
【チェック項目】
1. Wikiダンプ:package.json・README等を読めば分かる情報が含まれていないか
→ あれば削除候補をリストアップ
2. /init の残骸:自動生成されたと思われる情報が残っていないか
→ あれば削除候補をリストアップ
3. 曖昧なルール:「きれいに」「適切に」などの抽象表現がないか
→ あれば具体的な禁止事項に書き直す案を提示
4. 追記できていないルール:よくある間違いで追記すべき内容がありそうか
→ プロジェクトの内容から推測して提案
5. 1ファイル集約:ディレクトリ別に分割すべきルールがないか
→ あれば .claude/rules/ への振り分け案を提示
【私のCLAUDE.md】
(ここに内容を貼り付ける)
実践2:失敗パターンをすべて直した後のフォルダ構成
your-project/
├── CLAUDE.md # プロジェクト全体のルール(2,000トークン以内)
│ # ・アーキテクチャ方針
│ # ・プロジェクト全体の禁止事項
│ # ・ビルド・テストコマンド
│
├── CLAUDE.local.md # 個人設定(.gitignoreに追加)
│ は# ・ローカル環境の差異
│ # ・個人のAPIキーパス
│
└── .claude/
└── rules/
├── frontend.md # /app 配下のルール
│ # ・Server Components優先
│ # ・Client Componentsの制約
├── api.md # /app/api 配下のルール
│ # ・認証チェック必須
│ # ・エラーレスポンスの形式
└── database.md # /lib/supabase 配下のルール
# ・RLSポリシーを必ず通す
# ・直接DBに書かない
~/
└── .claude/
└── CLAUDE.md # グローバル設定(50行以内)
# ・全プロジェクト共通の習慣
# ・コミットメッセージのルール
ビフォー・アフターの違い:
【Before】
CLAUDE.md(500行・Wikiダンプ+/init残骸+曖昧ルール混在)
【After】
CLAUDE.md(50行・具体的なルールのみ)
.claude/rules/frontend.md(20行)
.claude/rules/api.md(15行)
.claude/rules/database.md(15行)
合計100行・すべて具体的・役割が明確
次回予告
第4回は Plan Mode開発手法(80/20ルール)。
タスクの80%でPlan Modeを使うべき理由、Read-onlyモードの活用法、「計画→実行」の正しいフローを解説する。CLAUDE.mdを正しく設計した上でPlan Modeを使うと、「計画フェーズでCLAUDE.mdのルールを前提にした設計」ができるようになる。2つの回がセットで機能する理由がここにある。