CLAUDE.md を書いても指示が通らない3パターンと直し方

CLAUDE.md を書いたのに Claude の振る舞いがぜんぜん変わらない——。

Claude Code を使い始めてしばらく経ったころ、自分もこの詰まり方をしていました。ルールを追記するたびに「今度こそ守ってくれるはず」と思うのに、翌日の実行を見ると同じ挙動を繰り返している。

この記事は、masatoman.net の CLAUDE.md / AGENTS.md / Skills を実際に設計・運用して出てきた「詰まりパターン3つ」の実験ログです。うまくいかなかった原因と、今も動いている解決策を記録します。

結論

CLAUDE.md の指示が通らない原因は、ほぼ次の3パターンのどれかです。

ファイルが長くなりすぎて後半が読み飛ばされている
スキルにトリガー条件が書かれていないので呼ばれない
禁止形で書いた指示が境界ケースで抜け落ちる

それぞれ原因と直し方が違います。順番に記録します。

この記事の前提（自分の状況・実験条件）

運用サイト: masatoman.net（記事 140 本以上）を Claude Code で半自動運用
スタック: Next.js 16（App Router）+ TypeScript + MDX + Vercel
AI 設計: CLAUDE.md / AGENTS.md の 2 層構成 + .claude/skills/ にスキルを 4 本 + .claude/hooks/ にフック 2 本

読者のよくある詰まり（「それ俺だ」を作る）

CLAUDE.md を書いて最初に詰まるのはこういう状況です。

ルールを書いたのに、翌日の実行で無視されている
スキルファイルを作ったのに、Claude が自分で使ってくれない
「〜しない」と明記したはずなのに、特定の操作では突破される

どれも「書いた内容は正しい。でも効かない」という詰まり方です。構文の問題ではなく、どこに何を書くか・どう書くかの設計問題です。

実際に起きたこと

パターン1: CLAUDE.md が長くなって後半のルールが読み飛ばされる

masatoman.net の CLAUDE.md は、プロジェクトが育つにつれて 100 行超になりました。ターゲット定義・技術スタック・記事執筆ルール・禁止パターン・推奨記事タイプ……と追記し続けた結果、後半に書いたルールが効かなくなり始めました。

原因: Claude は長いプロンプトを全部等しく読むわけではありません。コンテキストが長くなるほど、後半の内容は前半より確率的に影響力が落ちます。

直し方: 関心の違うルールは別ファイルに切り出して @import する。masatoman.net では冒頭に @AGENTS.md と書くことで、「Next.js の破壊的変更への注意」を AGENTS.md に分離しています。コンテキスト量を絞ると、残ったルールの効き目が上がります。

@AGENTS.md

# masatoman.net（AI業務設計の実験ログ）
...（本当に毎回必要なルールだけを残す）

パターン2: `.claude/skills/` に置いたスキルが呼ばれない

.claude/skills/ ディレクトリにスキルファイルを作っても、Claude は自動で使いません。「書いたら使ってくれる」という思い込みで詰まります。

原因: スキルはデフォルトで受動的です。Claude が「今このスキルを呼ぶべき」と判断するためには、スキルファイルに明示的なトリガー条件が必要です。

直し方: スキルの frontmatter か冒頭に、いつ呼ばれるべきかを書く。masatoman.net の publish-gate スキルなら「記事を公開する前に実行」という条件を、CLAUDE.md に「記事を公開する前に publish-gate skill を必ず invoke する」と明示しています。スキルファイル側の TRIGGER 説明と CLAUDE.md の呼び出し条件、両方に書くと確実です。

パターン3: 「〜しない」という禁止指示が境界ケースで抜け落ちる

「〇〇しない」「〇〇は禁止」と書いた指示が、特定の操作やフロー変化でスルーされることがあります。

原因: 禁止形は、コンテキストが変わると境界が曖昧になりやすいです。「しない」という指示は、何かの条件を満たしたときにだけ有効かが伝わりにくい。

直し方: 「〜しない」を「〇〇の場合のみ〇〇する。それ以外はしない」という条件付き許可形に書き直す。masatoman.net の content-executor プロンプトでは「実差分ゼロ or push 未 landed なのに published にするのは禁止（ゴーストpublish）」という禁止と同時に、Step 6 として「実差分チェック → push 検証 → 通った場合のみ published にする」という正の条件を明示しています。禁止だけでなく「何が OK か」を並記するほうが安定します。

原因分析

3つのパターンに共通する根本は「Claude が人間と同じように文章を読む」という前提で設計していること。

長いファイルは後半が弱くなる（人間も同じだが機械的な比率が違う）
受動的なスキルは自分から使わない（人間なら状況判断するが、ツールは明示が必要）
禁止形は「何をしてよいか」が残らない（人間は文脈補完するが、コンテキストが長いと補完精度が落ちる）

判断軸（自分のケースに当てはめる方法）

CLAUDE.md が効かないと感じたら、まず次の 2 点を確認します。

ファイルが 80 行を超えているか？ → YES なら別ファイルへの分割を検討
「〜しない」という禁止が 5 個以上あるか？ → YES なら条件付き許可形への書き直しを試す

スキルが呼ばれない場合は、CLAUDE.md の中に「いつ呼ぶか」の明示があるかを確認します。スキルファイルを作るだけでは動きません。

今日やること（3 つ以内）

自分の CLAUDE.md を開き、80 行を超えていたら切り出せるセクションを 1 つ探す
.claude/skills/ にスキルがあるなら、CLAUDE.md に「いつ呼ぶか」が書かれているか確認する
禁止形の指示を 1 つ選んで「条件付き許可形」に書き直してみる

これらは全部、masatoman.net を Claude Code で日常運用しながら実際に踏んだパターンです。きれいな理論ではなく、動いている構成から逆算した判断軸なので、同じ詰まり方をしているなら参考になるはずです。

AIにブログ運営を任せて効いたのはプロンプトより「決まった時間に動かす仕組み」

Claude の定期実行・共有ボード・役割ルールの3点セットで業務を半自動化した実験ログ

→