CLAUDE.mdにルールを書いた。Claude Codeはそれを読んでいる——確認すれば引用して見せてくれる。それでも、そのルールを破ったコードが生成される。
これはClaude Codeのイシュートラッカーで繰り返し報告されてきた問題で、同じルール違反が1セッション中に何度も発生したり、短いタスクでは守られていたルールが長いタスクで守られなくなったりする事例が記録されている。原因は一つではないため、「CLAUDE.mdをもっとよく書く」という対処が効く場合と効かない場合がある。
症状は同じでも、6つの異なる原因がある。4つはCLAUDE.mdを改善すれば解消できる。残り2つはCLAUDE.mdを改善しても解決しない構造的な問題だ。どれが当てはまるかを特定する方法を説明する。
1. ファイルが読み込まれていない
指示の内容を見直す前に、ファイルが読み込まれているかを確認する。
Claude Codeで /memory を実行すると、現在のセッションで有効なメモリファイルの一覧が表示される。~/.claude/CLAUDE.md（ユーザーレベル）、プロジェクトルートのCLAUDE.md、ディレクトリレベルのCLAUDE.md、CLAUDE.local.mdがすべてリストされる。編集したファイルが表示されていなければ、そのセッションには反映されていない。
読み込まれない主な原因：
起動ディレクトリのずれ。 Claude Codeは起動したディレクトリのCLAUDE.mdを読む。親ディレクトリから起動すると、サブディレクトリのCLAUDE.mdは読まれない。
ファイル名の大文字小文字。 claude.mdやClaude.mdは読み込まれない。ファイル名は正確にCLAUDE.mdでなければならない。
importパスの誤り。 @importで他のファイルを参照している場合、対象ファイルが存在しないかパスが間違っていると、そのセクションが無視される。
/memoryでファイルが読み込まれていることを確認した上でも問題が起きているなら、原因は次のいずれかになる。
2. 指示が抽象的すぎる
Anthropicの公式ドキュメントは、「具体的で的を絞った指示ほど一貫して機能する」と説明している。679個のエージェントルールファイルと5,000回以上のエージェント実行を分析した2026年のプレプリント（arXiv 2604.11088）では、より具体的なパターンが確認されている。「このように書け」という抽象的な肯定命令は、「これをするな」という具体的な否定的制約より行動変化への効果が弱かった。
実際の違いは次のようになる：
# 効果が弱い——モデルが解釈する余地がある
アーキテクチャに沿った、クリーンで保守しやすいコードを書くこと。
# 効果が強い——条件が明確で確認できる
src/components/ 内のファイルから @/lib/db を直接importしないこと。
console.logをコードに残してコミットしないこと。
APIエンドポイントを追加したら、同じディレクトリにテストファイルを作成すること。
前者は「クリーン」「保守しやすい」の解釈がタスクの文脈によって変わる。後者は、条件が成立しているかどうかが確認できる形になっている。
CLAUDE.mdを見直して、性質や品質を説明している指示を探す。可能な限り、具体的な制約に書き換える。具体化できないものは削除する——抽象的な指示はノイズになるだけで、信頼性には寄与しない。
3. ファイルが長すぎる
人気のOSSリポジトリ100件のCLAUDE.mdおよびAGENTS.mdを分析した2026年のプレプリント（arXiv 2606.15828）では、42%に「Context Bloat」が見られた。現在のタスクと無関係な内容が混在しており、重要なルールが希薄化されていた状態だ。
モデルが長いファイルを無視するわけではない。ただ、無関係な内容に埋もれたルールは、タスクに対する相対的な重みが落ちる。800行のファイルの450行目にある制約は、即座の問題解決という圧力と競合しており、多くの場合タスク側が優先される。
内容を整理してみる。コード生成に実際に必要な行と、ドキュメントや設定手順にすぎない行を区別する。CLAUDE.mdに入れる必要がない典型的な内容：
- アーキテクチャの図や説明（人間には有用だが、コード生成には不要）
- 開発サーバーやテストスイートの実行方法
- 変更履歴や設計決定ログ
- コード生成ではなく開発者が参照するための情報
残ったルールをスコープで分割する。Claude CodeはディレクトリレベルのCLAUDE.mdをサポートしている。APIレイヤー固有のルールは api/CLAUDE.md に、個人の設定はCLAUDE.local.md（gitignore対象）に置く。ルートファイルには、リポジトリ全体に本当に適用されるルールだけを残す。
4. ファイル間で指示が矛盾している
Claude Codeは複数のCLAUDE.mdを読み込む。ユーザーレベルの ~/.claude/CLAUDE.md、プロジェクトルート、サブディレクトリが対象になる。これらの間で同じ行動について異なる指示が書かれていると、モデルの挙動が一定しなくなる。
上記のプレプリントでは、「Conflicting Instructions」がContext Bloatと同時に発生するケースが多く確認された。チームがプロジェクトのCLAUDE.mdにルールを追加する一方で、各開発者のユーザーレベルファイルに別のスタイル設定がある、あるいはリファクタリング後に古いディレクトリCLAUDE.mdが削除されずに残っているというパターンが典型的だ。
別のプレプリント（arXiv 2606.09090）では、分析対象の23%のリポジトリで、CLAUDE.md内に削除・リネームされたコード要素への参照が見つかった。存在しないモジュールを参照するルールは、せいぜいノイズで、最悪の場合、現在の構造を記述している別のルールと矛盾する。
診断方法：/memory を実行して読み込まれているすべてのファイルを確認し、同じ行動について異なる方向を示している指示を探す。古い参照を削除し、矛盾を明示的に解消する。
5. タスクの指示に押し負ける
原因1から4はCLAUDE.mdファイル自体の問題だ。原因5はClaude Codeがコンテキストを処理する方法の性質に起因する。
CLAUDE.mdの内容は、コンテキストとして読み込まれる。Anthropicの公式ドキュメントはCLAUDE.mdを「Claudeへのコンテキスト」と説明しており、「強制設定ではない」と明記している。モデルはCLAUDE.mdの内容をタスクの指示、既存のコード、即座の問題を解決するための最短経路と比較しながら判断する。CLAUDE.mdのルールが必ず優先されるわけではない。
短いセッションでは守られるルールが、長いタスクでは守られなくなる理由がこれだ。会話が長くなるにつれてタスク固有のコンテキストが増え、CLAUDE.mdのルールの相対的な比重が下がる。
この構造的な問題と、決定論的な事前マージチェックによる対処については、AIコーディングエージェントがアーキテクチャの乖離を引き起こす理由で詳しく説明している。
例外なく守られなければならないルールには、コンテキストの重みに依存しない仕組みが必要だ。Claude Codeの設定で利用できる PreToolUse フックは、ツール呼び出しの前にスクリプトを実行し、非ゼロで終了した場合に操作をブロックする。CIチェックはエージェントセッションとは独立して実行される。
6. ルールが守られたか確認する手段がない
/memory は何が読み込まれているかを示す。最後に生成されたコードで各ルールが適用されたかどうかは、何も表示しない。
確認手段がなければ、違反は静かに蓄積する。レビュアーが気づいたとき、あるいは数週間後にパターンとして発覚したときに初めてわかる。
信頼性の高い順に確認手段を挙げる：
動作テスト。 CLAUDE.mdを変更した後、主要なルールが発動するはずのタスクをClaude Codeに実行させ、出力を確認する。定期的に実行することで、本番コードに到達する前に問題を捕捉できる。数分でできる。
フック。 PreToolUseとPostToolUseフックを設定すると、特定の操作の前後にスクリプトを実行できる。提案された編集にforbidden importが含まれるかを確認するフックは、適用される前にブロックできる。これは決定論的だが、制約ごとにスクリプトを作成・維持する必要がある。
CIチェック。 アーキテクチャの制約をCIルールとして表現すると、エージェントセッションの内容に関係なく、すべてのPRで実行される。forbidden importを検出するTree-sitterクエリやgrepベースのチェックは、エージェントとレビュアーの両方が見逃した違反を捕捉する。Unbxはこの種の事前マージアーキテクチャチェックを実装している——エージェントのセッション内での遵守ではなく、出力に対してルールを実行する仕組みだ。
修正できる問題と、構造的な問題
原因1から4は、CLAUDE.mdを改善することで解消できる。ファイルの読み込みを確認し、具体的な制約を書き、ノイズをトリミングし、矛盾を解消する。説明のつかない指示不遵守の多くは、このグループに属する。
原因5は構造的な問題だ。CLAUDE.mdのルールを具体的に保ち、ファイルを短くすることで違反の頻度を下げることはできるが、なくすことはできない。モデルは常にコンテキストとタスクを比較しながら動く。例外なく守らせたいルールには、フックかCIチェックが適切な仕組みになる。
原因6は、他の問題の診断を難しくする。確認手段がなければ、どの原因が当てはまるかわからない。まず /memory で読み込みを確認し、主要なルールに対して動作テストを追加し、CLAUDE.mdを「一度設定して信頼する」ポリシーではなく、違反が出たときに見直す作業ドキュメントとして扱うのが現実的なアプローチだ。