コーディングエージェントが指示を無視する原因と対策
指示ファイルが無視されるのはなぜか。モデルのコンテキストウィンドウにおける情報の優先順位と、ハーネスが命令をメッセージとして扱う仕組みを解説します。指示を強制するための具体的なフックの導入方法と、トラブルシューティングの手順をまとめました。
コーディングエージェントが指示を無視する理由
コーディングエージェントが指示を無視する理由は 4 つあります。どれも、指示の伝え方が丁寧すぎることではありません。そのルールがコンテキストウィンドウに入っていなかった可能性があります。ルールが曖昧で、アクションと照合できなかった可能性もあります。コンテキスト内の別の内容、通常はエージェントが直前に読んだコードが、ルールと矛盾していた可能性もあります。または、ルールは読み込まれていても現在のターンから遠く、エージェントが近くにある情報を基に処理している可能性があります。
原因ごとに対処方法は異なります。そのため、最初に原因を区別する必要があります。大文字や IMPORTANT という語を使っても、原因の特定にはなりません。以下では、動作の詳細が 2026 年 10 月時点で文書化されている Claude Code を例に説明します。他のツールでは細部が異なりますが、全体的な動作は同じです。
最初に 2 つの用語を説明します。コンテキストウィンドウは、特定のターンでモデルが参照するテキストのまとまりです。システムプロンプト、指示ファイル、会話、エージェントが読み込んだすべてのファイルが含まれます。ハーネスはモデルの周囲で動作するプログラムです。ディスクからファイルを読み込み、そのまとまりを組み立てます。この記事に対する不満のほとんどは、実際にはモデルではなくハーネスに対する不満です。
命令ファイルは設定ではなくメッセージです
命令ファイルは設定ではありません。ランタイムが CLAUDE.md を読み取り、強制適用することはありません。ハーネスはディスク上のファイルを読み込み、そのテキストを会話に貼り付けます。Claude Code では、その内容は system prompt の後に置かれる user message として渡されます。つまり、モデルには、入力した他のテキストと同じようにルールが表示されます。
ここから不都合な結果が生じます。ルールは、ウィンドウ内の他のすべてのテキストと同じ土俵で競合します。ルールは主張です。エージェントが直前に開いたファイルは証拠です。この2つが食い違うと、証拠が優先されることがよくあります。その場合もエラーは発生しません。モデルから見ると、問題は何も起きていないためです。
公式ドキュメントにも明記されています。命令ファイルは、強制される設定ではなくコンテキストとして扱われます。モデルの判断に関係なく操作をブロックするには、文ではなく hook が必要です。この点を覚えておいてください。この記事の最後に示す修正の多くは、この原則を特定のケースに適用したものです。
読み込まれる指示ファイルと、そのタイミング
Claude Code は、起動したディレクトリからディレクトリツリーを上方向にたどります。ファイルシステムのルートから作業ディレクトリまでにあるすべての CLAUDE.md と CLAUDE.local.md は、起動時に完全に読み込まれます。これらはその順序で連結されるため、起動した場所に最も近いファイルが最後に読み込まれます。同じディレクトリ内では、.local ファイルがメインファイルの後に追加されます。
作業ディレクトリより下のサブディレクトリにあるファイルは、動作が異なります。起動時には読み込まれません。エージェントがそのディレクトリ内のファイルを読み込んだ時点で読み込まれます。.claude/rules/ のパススコープルールに paths: frontmatter フィールドがある場合も同じです。一致するファイルが読み込まれた時点でコンテキストに追加され、ターンごとに追加されるわけではありません。v2.1.309 以降、この方法で読み込まれるファイルにはファイル単位のサイズ制限もあります。200K のコンテキストウィンドウでは 40,000 文字です。長いファイルの場合、エージェントに渡されるのは先頭部分だけです。そのため、大きなネストファイルの末尾付近にあるルールがコンテキストに入らないことがあります。
この違いだけで、報告されている失敗の多くを説明できます。packages/api/CLAUDE.md にルールを記述し、API について質問したものの、エージェントが packages/api/ 配下のファイルを一度も開かなかったとします。そのルールが無視されたわけではありません。そもそもコンテキストに存在しなかったのです。リポジトリで モノレポのパッケージごとの指示ファイル にガイダンスを分割している場合は、毎回まずここを確認してください。
AGENTS.md を標準化しているリポジトリには、もう 1 つ読み込みに関する注意点があります。v2.1.277 以降、Claude Code はデフォルトで AGENTS.md をプロジェクトの指示として読み込みます。ただし、作業ディレクトリまたはその上位のディレクトリに CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のいずれも存在しない場合に限ります。個人用の ~/.claude/CLAUDE.md はこの判定対象外です。これらのいずれか 1 つでも追加すると、個人的なメモ用の CLAUDE.local.md であっても、Claude Code は代わりに CLAUDE.md ファイルを読み込み、AGENTS.md を完全に除外します。両方を読み込むには、/config の Project instructions を claude-md-and-agents-md に設定します。v2.1.277 より前のバージョンで使用する場合、または CLAUDE.md を残したい場合は、先頭行を @AGENTS.md にした CLAUDE.md をブリッジとして使用します。このファイルは起動時に対象ファイルを読み込み、その下に Claude 固有のメモを記述できます。追加する内容がなければ、シンボリックリンクも使用できます。そもそもそのファイルに何を記述するかは別の問題であり、エージェントの指示と人間向けドキュメントの分離で説明します。
ファイルを書き換える前に、読み込まれたことを確認する
エージェントがファイルを認識できる証拠を得るまで、文言を変更しないでください。確認方法は2つあります。まず、簡単な方法から実行します。
セッション内で /context を実行します。現在のウィンドウをカテゴリ別に表示し、起動時に読み込まれたすべての指示ファイルを Memory files リストに示します。このリストにないファイルは起動時に読み込まれていません。そのため、何かが読み込むまで、そのファイル内に記述しても効果はありません。サブディレクトリ内のネストされたファイルはオンデマンドで読み込まれるため、リストには表示されません。読み込まれると、パスを示す Loaded 行がターミナルに表示されます。/memory はファイルの場所を一覧表示し、まだ存在しないファイルも含めて編集用に開きます。
より確実に確認するには、読み込みを記録します。InstructionsLoaded フックイベントは、CLAUDE.md またはルールファイルがコンテキストに入るたびに発生します。matcher により、読み込みの理由が session_start、nested_traversal、path_glob_match、include、compact のいずれかとして示されます。.claude/settings.json に次の内容を記述します。
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}フックは標準入力から JSON としてペイロードを受け取るため、cat によりレコード全体を追記できます。作業中は tail -f /tmp/instructions-loaded.log で監視します。このイベントの終了ステータスは無視されるため、フックは監視のみを行い、処理をブロックすることはありません。読み込まれるはずのセッション中にネストされたファイルがそのログに一度も現れない場合は、文言の修正を中止してください。問題は配置にあります。例外として、Claude Code が直接読み込む AGENTS.md ではこのイベントは発生しません。そのため、代わりに /memory でパスを確認します。CLAUDE.md からインポートされた AGENTS.md では、通常どおりイベントが発生します。
長いセッションがルールに与える影響
ここでは、2 つの異なる影響があり、それぞれに別の対応が必要です。
距離。 コンパクションが実行されるまでは、turn 1 で指定したルールが turn 90 でもコンテキスト内に残っています。ただし、その時点では、現在の作業に関する、より新しく、より具体的な 90 turn 分のテキストと競合します。コンパクションが実行されると、チャットに入力しただけのルールはコンテキスト内にまったく残らない場合があります。Claude Code のドキュメントでも、会話の初期に指定した指示が失われる可能性があると説明されています。これが次に説明する 2 つ目の影響です。距離の影響を設定でなくすことはできませんが、測定はできます。新しいセッションで同じタスクを実行してください。そこでルールが維持され、長いセッションの途中で失敗するなら、原因は距離またはコンパクションです。
コンパクション。 コンテキストウィンドウが満杯になると、ハーネスはそれまでの会話を要約し、その要約を基に処理を続けます。残るのは、要約処理が重要だと判断した内容です。それは、あなたが重要だと考える内容とは限りません。Claude Code では、各メカニズムについて結果が文書化されており、違いは大きくなります。プロジェクトルートの CLAUDE.md とスコープ指定のないルールは、コンパクション後にディスクから再注入されます。自動メモリもディスクから再注入されます。paths: frontmatter を持つルールは、対応するファイルが再度読み込まれるまで失われます。サブディレクトリ内のネストされた CLAUDE.md ファイルは、そのサブディレクトリ内のファイルが再度読み込まれるまで失われます。
この表に従って指示を順位付けすると、脆弱性の順序が明確になります。チャットに入力しただけのルールは、そのセッションで最も脆弱です。要約に偶然残った場合にだけ維持されます。packages/api/CLAUDE.md 内のルールが次に続きます。これは一度読み込まれた後に要約で失われ、そのディレクトリ内で次に読み込みが発生したときだけ戻ります。プロジェクトルートのファイル内のルールは、毎回ディスクから再読み込みされるため、最も永続性があります。
したがって、セッション全体で指示を維持する必要がある場合は、paths: frontmatter を付けずに、プロジェクトルートのファイルへ記述してください。それ以外は、目的を明確にしたうえで選択すべきトレードオフです。コンテキストウィンドウに残す内容の管理では、フォーカス引数を使用する /compact と、無関係なタスク間の /clear を扱います。どちらも、要約処理がルールの内容を判断する頻度を変えます。
周辺のコードがルールに勝る理由
これは、最も頻繁に説明される一方で、原因の特定が最も少ない失敗です。ファイルには、データベースアクセスはリポジトリ層を経由すると書かれています。しかし、エージェントは ORM(オブジェクトリレーショナルマッパー)を直接呼び出すハンドラーを作成します。これは、スタイル上の理由で指示を無視したのではありません。根拠の強さで負けたのです。
ルールは、望ましい方針を示します。コードは、その方針の実例を示します。エージェントが編集対象のモジュールで 3 つのファイルを開き、そのすべてが ORM を直接呼び出している場合、コンテキストの一方には抽象的な文が 1 つあり、もう一方には具体的で新しく、今回のタスクに合った例が 3 つあります。通常、ローカルのパターンをコピーするのが正しい動作です。ただし、ここでは誤りになります。あなたはコンテキストにない情報を知っているからです。そのファイルはレガシーコードです。
そのため、その情報をルールに書き込みます。反証となるコードを自分で明示するルールは、実際のリポジトリでも機能します。単なる好みを述べるだけのルールは機能しません。
新しいデータベースアクセスはapp/repositories/を経由します。app/legacy/配下のファイルは、現在も ORM を直接呼び出しています。これは古いコードであり、標準パターンではありません。コピーしないでください。
効果を生むのは 2 文目です。エージェントがそのコードを見つける前に、何を見つけることになるのか、そしてそれをどう解釈すべきかを伝えています。同じ修正は、リポジトリが目に見える形で矛盾しているあらゆるルールに適用できます。たとえば、履歴に従っていないコミット形式、テストスイートの半分が無視しているテスト配置、新しいコードでしか守られていない import 規約などです。コードとファイルの内容が食い違う場合は、その食い違いをファイルに明記してください。
確認できない曖昧なルールは、従うこともできません
「クリーンなコードを書く」「過剰に設計しない」「シンプルに保つ」「マイグレーションには注意する」。これらは、エージェントもあなたも、特定の操作に対して検証できません。自分の出力に照らして確認できないルールを与えられたエージェントは推測するしかなく、あなたはその推測を感覚で評価することになります。
ファイル内のすべての行に、次のテストを適用してください。ルールに違反したときに終了ステータスが 0 以外になる shell コマンドを書きます。そのコマンドを書けないなら、そのルールは検証可能ではありません。次の組み合わせを比較してください。
- 検証不可: 「関数を小さく保つ」 検証可能: 「60 行を超える関数の上には、その長さが必要な理由を説明するコメントを置く」
- 検証不可: 「変更をテストする」 検証可能: 「タスクを完了とする前に
npm testを実行し、失敗数を貼り付ける」 - 検証不可: 「ファイルを整理して保つ」 検証可能: 「HTTP ハンドラーは
src/api/handlers/に置く。それ以外のものはそのディレクトリに置かない」 - 検証不可: 「コードを適切にフォーマットする」 検証可能: 「
.tsファイルでは 2 スペースのインデントを使用する」
「過剰に設計しない」は、最初に諦められやすいルールです。修正方法は短い文にすることではなく、長い文にすることだからです。実際に機能する最小の変更が何を意味するのかを明記することで、エージェントが自分の差分と照合できる基準を与えられます。
サイズも、別の形で同じ問題になります。Claude Code のガイダンスでは、1 つの指示ファイルを 200 行未満にすることを目標とし、ファイルが長いほど指示への準拠率が下がると明記しています。700 行のファイルは、より強い指示ではありません。互いに矛盾する可能性が高い主張が 700 行並んでいるだけです。しかも、すべてのターンでウィンドウの容量を消費するため、トークン使用量に直接現れます。各ルールを読者が確認しやすい見出しの下に配置する方法については、エージェントが実行できる指示ファイルの書き方で説明しています。さらに良い方法は、指示ではなく説明になっている部分を削ることです。ハンドラーやモデルの場所を列挙するディレクトリ案内は、毎回ウィンドウに保持するのではなく、解析済みのリポジトリマップからエージェントが必要なときに参照できる構造です。
10 分で原因を切り分ける方法
次の手順を順番に実行します。最後の手順にいきなり進むと、強い表現のルールを大量に書いたにもかかわらず、動作しない状態になります。
- 読み込まれたことを確認します。
/contextを実行して Memory files の一覧を確認します。ネストしたファイルの場合は、ターミナルでLoadedの行を探します。ファイルが一覧にない場合は、場所を修正して手順を終了します。まだ、この一覧にある他の項目は適用できません。 - 新しいセッションで再現します。 新しいセッションを開始し、ルールが適用されるはずの最小限のタスクを指定します。ここでは適用されるものの、長いセッションで失敗する場合は、距離またはコンパクションが原因です。ここでも失敗する場合は、ルール自体に問題があります。
- 競合要因を取り除きます。 既存のコードがすでにルールに従っているディレクトリで、同じ変更を依頼します。遵守されるようになった場合は、周囲のコードが指示文より強く作用していました。
- 競合を検索します。 同じ動作について異なる指示を記載したファイルが 2 つあると、既知の失敗が発生します。モデルはどちらかを任意に選ぶ可能性があり、そのことを知らせません。
- 確認可能な形にして再テストします。 具体的なパスと条件を含むようにルールを書き換えます。遵守率が大きく向上した場合は、原因は表現方法にあります。
手順 4 は 1 つのコマンドで実行できます。編集中のファイルだけでなく、すべての指示ソースから対象トピックを検索します。
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null異なる内容を記載したファイルが 2 つ見つかった場合、それが原因です。一方を削除します。より強い表現で優先順位を付けようとしてはいけません。優先順位を判定するエンジンは存在しないためです。Claude Code v2.1.283 以降では、/doctor prompt-audit により、この検索を指示ファイル、ルール、スキル全体に広げて実行できます。矛盾と修正案が報告されますが、依頼するまでは内容は変更されません。
効果の高い順に見た修正方法
以下の各手順は、上にある手順よりも大きな効果があります。その分、設定にも手間がかかります。ルールの文言を変更するだけで済む場合は、最初の手順から始めてください。ルールが重要になり、たまに見落とされることも許容できなくなった時点で、下の手順へ進みます。
- ルールを具体化します。 パス、コマンド、または条件を明記します。前述の例のように、エージェントがリポジトリ内で確認できる反証も追加します。費用はかからず、多くのケースを解決できます。
- 適用対象の近くに移します。 ネストした
CLAUDE.md、.claude/rules/のパススコープルール、またはファイル先頭のコメントなどです。ルールと適用対象のコードが同じ読み取り処理で読み込まれるようになります。ただし、これによるトレードオフがあります。この方法で読み込まれた内容は、次の圧縮時にコンテキストから外れ、次に一致する読み取り時に再び読み込まれます。 - フックに強制処理を移します。 プローズは要求するだけですが、フックは判断します。フックはライフサイクル上の固定イベントでコードとして実行され、モデルの判断に関係なく適用されます。
- ルールを決定論的なツールに任せ、プローズを削除します。 フォーマット、import 順、行の長さ、禁止された import、コミットメッセージの形式などです。
ruff format、prettier --write、eslint、またはpre-commitフックを使用します。フォーマッタは常に正しく動作し、トークンを消費しません。文章によるルールは多くの場合は正しく機能しますが、ターンごとにトークンを消費します。
手順 3 の詳細を説明します。エージェントが migration ファイルを絶対に編集してはならない場合を考えます。.claude/settings.json に次の内容を追加します。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}.claude/hooks/guard-migrations.sh には次の内容を追加します。
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0chmod +x .claude/hooks/guard-migrations.sh を実行してから、新しいセッションを開始し、migrations/ 配下のファイルを編集するようエージェントに依頼します。編集は拒否され、その理由がメッセージとして返されます。PreToolUse で終了ステータス 2 を返すと、ツール呼び出しが実行される前にブロックされ、stderr のテキストがブロック理由としてモデルに渡されます。${CLAUDE_PROJECT_DIR} はプロジェクトルートに解決されるため、エージェントがどのディレクトリにいてもフックは機能します。エージェントがルールに同意したり、ルールを記憶したり、コンテキスト内にルールを保持したりする必要はありません。編集は実行されません。
論理を含まない単純な禁止であれば、設定内の permissions.deny でも同じことを実現できます。保守するスクリプトは不要です。また、権限モードによって、事前確認なしで実行される処理を決められます。指示を本当にシステムプロンプトのレベルに置く必要があり、ユーザーメッセージには置けない場合は、--append-system-prompt で指定できます。ただし、これは新しいセッションごとに再度渡す必要がある起動フラグです。そのため、対話的な作業よりもスクリプトに適しています。
指示だけではなくせないこと
この問題のうち、どこまでが自分の責任かを明確にしてください。配置、表現、ファイル間の競合、ファイルサイズは作成者の問題であり、作成者が修正するものです。それ以外はモデルの挙動に関する問題で、表現を改善してもなくなりません。
同意は遵守ではありません。 エージェントはルールを認め、正しく言い直したうえで、2 回後のツール呼び出しで破ることがあります。同意にはコストがなく、予測材料にもなりません。修正と見なさず、テスト結果にも数えないでください。
一部の習慣は残り続けます。 コメントを追加する、防御的なエラーハンドリングを書く、最後に要約する、次に行うべき明らかなコマンドを実行する、といった習慣です。これらは、禁止するルールがあっても、発生率が下がるだけでゼロにはなりません。同じタスクを新しいセッションで 10 回実行し、違反数を数えれば、自分の発生率を測定できます。その数をゼロにする必要がある場合、そのルールをプロンプトから外す必要があります。作業の一部がまだ終わっていないのに完了と判断するのも、同じ種類の習慣です。修正方法は文言ではなく構造にあります。unlazy skill はその一文を Depth Tree に置き換え、完了を主張する前にエージェントが通過する必要のある gate file を設けます。
自分のセッション自体が実例になります。 エージェントが turn 12 でルールを破り、それを見逃した場合、その違反はコンテキストに実例として残ります。しかも、ルールよりはるかに新しい情報です。違反を見つけたら、その場で訂正してください。訂正されなかった違反は、セッションの残りの部分に教訓として伝わります。
指示ファイルはセキュリティ境界ではありません。 指示ファイルは挙動を方向付けるだけで、強制はしません。認証情報や破壊的なコマンドなど、失敗時の影響が大きいものは、権限または hook で制御してください。エージェントの手の届かない場所に Secret を置くという原則は、データにも同じように適用されます。エージェントにファイルを読まないよう求めるのではなく、そのファイルを読み取れない状態にしてください。
要点は簡単です。ファイルが読み込まれたことを確認し、ルールを検証可能にし、対象のすぐ近くに配置してください。それでも違反率が問題になる場合は、ルールを文章から外してください。エージェントが無視できないルールは、最初からエージェントに求めるルールではありません。
FAQ
Claude Code が CLAUDE.md を無視するのはなぜですか?
無視されたと判断する前に、読み込まれたか確認してください。/context を実行し、Memory files の一覧を確認します。一覧にないファイルは、起動時に読み込まれていません。指示ファイルは system prompt の後に user message として渡され、強制設定ではなくコンテキストとして扱われます。そのため、厳密に従う保証はありません。実際には、主な原因は次の4つです。ファイルが agent の読み込み対象外のサブディレクトリにある、複数のファイルで内容が食い違っており model が任意に一方を選んだ、ルールが曖昧で実際の操作と照合できない、または周囲のコードがルールと反対の動作を示している、のいずれかです。
セッションの途中で指示ファイルを編集すると、何か変わりますか?
すでに会話に読み込まれた内容は変わりません。作業ディレクトリより上位にあるファイルは起動時に全文が読み込まれるため、model が保持するのは起動時点の内容です。編集内容を反映するには、新しいセッションを開始するか、通常のファイル操作ツールで agent にファイルを読み込ませます。これにより、現在の内容が新しいメッセージとして会話に追加されます。compaction 後は、プロジェクトルートのファイルがディスクから再読み込みされるため、その時点で新しい内容も反映されます。
ルートの CLAUDE.md とネストしたファイルの内容が食い違う場合、どちらが優先されますか?
どちらも確実には優先されません。検出されたファイルは上書きではなくコンテキストに連結されます。ファイルシステムのルートから作業ディレクトリに向かう順序で並ぶため、最も近いファイルは単に最後に読み込まれます。矛盾を解決する優先順位エンジンはありません。Claude Code のドキュメントにも、矛盾するルールは任意に解決される場合があると記載されています。ネストしたファイルは、対象となるパスを明記した追加ルールとして記述してください。優先順位で上回ろうとせず、矛盾する記述を削除します。
指示は /compact 後も維持されますか?
読み込まれ方によって異なります。プロジェクトルートの CLAUDE.md、スコープ指定のないルール、auto memory は compaction 後にディスクから再注入されます。paths: frontmatter を持つルールと、サブディレクトリ内のネストした CLAUDE.md ファイルは、対応するファイルが再度読み込まれるまで失われます。チャットに入力しただけの内容は、要約処理で保持された場合に限り残ります。セッション全体で維持する必要があるルールは、paths: frontmatter を付けずにプロジェクトルートのファイルへ記述してください。
ルールを文章ではなく hook にすべきなのは、どのような場合ですか?
判定が決定論的で、チェック漏れのコストが小さなスクリプトを書くコストを上回る場合です。ファイルパスの制限、commit 前に必須のコマンド、禁止する tool call などが該当します。status 2 で終了する PreToolUse hook は tool call を直ちにブロックし、stderr の内容を理由として model に返します。そのため、ルールがコンテキスト内に残っているかどうかに関係なく適用されます。formatter や linter が判定できる内容は、それらのツールに任せ、指示ファイルから完全に削除してください。