指示ファイルを増やしたのに、なぜAIの挙動が不安定になるのか
最初は「ルールを足せば安定する」と思っていました。ところが実際には、指示ファイルを増やすほど挙動がぶれ始めました。AGENTS.mdにもCLAUDE.mdにも似たような注意を書き、あとから見るとどちらが正本なのか分からない。修正のたびに両方を書き換える必要があり、片方だけ更新して差し戻される。そんな往復が続きました。
この詰まりは、書く量の問題というより、置き場所の問題でした。何をどこに書くかを決めないまま増やすと、ルール同士がぶつかります。読者がハマりやすいのも、まさにここです。
結論: AGENTS.mdとCLAUDE.mdは優劣ではなく役割で分ける
先に結論を書くと、AGENTS.mdとCLAUDE.mdは「どちらが正しいか」で選ぶものではありません。役割で分けると、運用は安定しやすくなります。
このリポジトリでは、次のように分けています。
- AGENTS.md: 全体方針、優先順位、禁止事項、承認ゲートなどの正本ルール
- CLAUDE.md: Claude Codeで作業するときの補助や橋渡し
要点は、同じルールを二重で持たないことです。AGENTS.mdを正本に置き、CLAUDE.mdでは必要に応じて参照する。これだけでも、更新漏れや差し戻しの原因を見つけやすくなりました。
ここでひとつだけ注意があります。この記事で紹介するのは、あくまでこのリポジトリでの運用例です。導入前には、必ず公式仕様を確認してください。
公式情報から分かることを、実務判断に変換する
公式情報を読むと、仕組み自体ははっきりしています。
OpenAIのCodex側では、AGENTS系ファイルを階層で探索し、作業ディレクトリに近い指示ほど後段で効く構造が示されています。AnthropicのClaude Code側では、CLAUDE.mdを階層的に読み込み、必要ならCLAUDE.mdからAGENTS.mdを参照できることが明示されています。
ただ、実務で重要なのは仕様の暗記ではありません。判断に変換することです。
- 階層で効き方が変わるなら、全体ルールと局所ルールを混ぜない
- 参照連携が使えるなら、同じルールをコピペで重複させない
- スコープがあるなら、誰が変更できるかを先に決める
仕様を並べるだけだと、読んだ直後は分かっても運用は変わりません。実際に変わるのは、配置と責任を決めたときです。
実務での分け方: どこに何を書くか
このテーマで一番効いたのは、ファイルごとの担当を先に固定することでした。
AGENTS.mdに書くこと
- サイト運用の目的
- 全体の優先順位
- 禁止事項
- 承認ゲート
- 正本と参照資料の扱い
CLAUDE.mdに書くこと
- Claude Code固有の補助
- AGENTS.mdへの参照
- Claudeでだけ使う作業メモ
- 局所的な補助ルール
書かない方がよいこと
- 同じルールの重複
- すでに廃止した古い運用ルール
- 承認責任が曖昧な指示
ここでの判断基準はシンプルです。「他のツールにも効く全体方針か」「Claude作業に限定される補助か」で分ける。迷ったらAGENTS.mdに寄せ、CLAUDE.mdには補助だけを書くほうが崩れにくくなります。
自分たちが詰まって修正した運用ログ
この整理は、机上で作ったものではありません。実際に混線して止まったあとで、少しずつ直してきました。
docs/current/とdocs/reference/legacy-revenue-ops/を分け、現行正本と過去資料を切り離した- 旧Revenue Ops資料を現行運用の判断根拠から外した
- Editorial Style Guideを追加し、本文の文体と禁止表現を固定した
- Global Practice Gateを追加し、公式要約だけで記事を終わらせない運用に変えた
- X投稿ドラフトやAffiliate Candidate Gateを後から連動させ、公開後工程を可視化した
こうした追加が増えるほど、正本と補助の境界は必要になります。境界が曖昧なままだと、ルールの数に比例して迷いも増えます。
あわせて、指示ファイルの整理だけでなく情報配置もそろえると、更新漏れを減らしやすくなります。具体的な整理手順は4分類で整える情報設計の記事でまとめています。
初心者が最初の1週間でやること
最初から完璧に設計する必要はありません。次の順番で十分です。
- AGENTS.mdに全体方針だけを書く
- CLAUDE.mdではAGENTS.mdを参照し、Claude固有の補助だけ書く
- 公開・投稿・収益に関わる判断は、人間承認で止めると明記する
- 1週間だけ運用し、差し戻し理由を記録する
この4つを回すと、どこで詰まっているかが見えるようになります。そこが見えれば、次に直す場所も決めやすくなります。
まとめ: 正本と補助を分けると、差し戻しは減らしやすい
指示ファイルは、増やすこと自体が目的ではありません。正本と補助を分けることが先です。
AGENTS.mdとCLAUDE.mdの役割を決めると、AIの出力ブレと差し戻しの原因を追いやすくなります。特に、どこに何を書くかを固定すると、更新時の迷いが減ります。
次に試すなら、まず自分のリポジトリで「これは全体方針か、ツール補助か」を二分してください。1週間運用して、差し戻し理由を3件だけ集める。そこから直すのが、いちばん再現しやすい進め方です。