目次
Claude Code を本格的に触り始めてしばらく経つのですが、いろいろ試した結果、リポジトリのルートに CLAUDE.md も AGENTS.md も置かない運用に落ち着きました。
最初は「プロジェクトのお作法は最初に全部渡しておくべき」と思っていたんですが、コンテキスト長と精度の関係を調べ直していくうちに、むしろ置かない方が安定して動くようになりました。この記事では、まずなぜ毎回読み込まれるルールファイルが AI の性能を落とすのかを整理し、そのうえで自分が代わりに採っている Skill 中心の運用について書きます。
なぜ CLAUDE.md は AI の性能を落とすのか
入力が長くなるほどLLMの出力は劣化する
「コンテキストウィンドウが伸びたから、たくさん渡しても大丈夫」と直感的には思いがちですが、研究を見るとむしろ逆のことが分かってきています。
よく引用されるのが、Stanford らの「Lost in the Middle」という研究[1]です。長い入力の中で関連情報が中央付近にあると、先頭や末尾にあるときと比べて性能が30%以上落ちる、という報告でした。
LLM は入力全体を均一には見ておらず、先頭と末尾に注意が偏る U 字型のバイアスがあると示されました。中盤に詰め込んだ指示やコードは、そもそも読まれにくい可能性がある、ということになります。
もっと最近のものだと、Chroma が2025年7月に「Context Rot」という技術報告[2]を出しています。GPT-4.1・Claude 4・Gemini 2.5・Qwen3 を含む18の最先端モデル全てで、入力トークンが増えるほど出力品質が劣化することを実測した内容です。
重要なのは、これが「ウィンドウ上限に達したとき」ではなく 入力が長くなり始めた時点から徐々に起きる 点です。200K トークンを謳うモデルでも、50K トークン付近からすでに目に見えて劣化することが示されています。
報告の中では、コーディングエージェントの主要な失敗モードは context rot だ、とまで言い切られています。検索・ファイル読み込み・試行錯誤の過程でコンテキストにノイズが積もっていき、それが後段の出力をじわじわ汚していく、という話です。
入力が太ると、出力に使える余地は物理的に減る
これは推論コストの話だけではなくて、API の作りとしてもそうなっています。Claude も GPT も、いわゆる「コンテキストウィンドウ」は input と output を合わせた合計予算として定義されていて、output 側にはさらに max_output_tokens のような上限が別に乗っています[3] [4]。
Claude Opus 4.7 と Sonnet 4.6 は 1M トークンのコンテキストですが、1リクエストで返せる出力上限はそれぞれ 128K と 64K に絞られています[4:1]。OpenAI 側も同じ構造で、GPT-4.1 は 1M コンテキストに対して output 上限が 32K しかありません[3:1]。
何が起きるかというと、input でコンテキストを使うほど、残りの予算が output に使える量を圧迫していきます。1M ウィンドウのうち 700K を input で使ったら、output に使えるのは残り 300K 以下になります。CLAUDE.md で先頭に毎回大量に詰める運用は、AI が1回の応答で書けるコードの量や説明の厚みを物理的に奪っているわけです。
AI企業側もコンテキストを「削る」方向に動いている
おもしろいのは、これに対する Anthropic 側の対策も、コンテキストを膨らませる方向ではなく削る方向に寄っていることです。
- prompt caching: 同じ前置き部分を再利用してコスト最大90%・レイテンシ最大85%削減[5]
- Claude Code の auto-compaction: 以前はウィンドウの90%超でトリガーしていたが、新しいバージョンでは64〜75%で要約圧縮を走らせるようになっている[6]
- context editing / memory tool: 古い検索結果やツール出力を会話から積極的に消す仕組み。100ターンの web 検索評価で、消さなければ失敗していたタスクを完了させつつ、トークン消費を84%削減したと報告されている[7]
「広い文脈を渡せます」ではなく「いかに渡さずに済ませるか」が、API・エージェント基盤の両側で主戦場になっている、というのが今の景色です。
Anthropic 自身も「Effective context engineering for AI agents」というエッセイの中で、コンパクション・外部メモリ・サブエージェント分割の三本柱でコンテキストを管理することを推奨しています[8]。
トークン経済の観点から見ても、入力が短く済むほど提供側の計算コストは下がります。企業側の利益構造とユーザー側の品質要求は実は同じ方向を向いているわけで、コンテキストを節約する設計に今後さらに最適化されていくのは自然な流れです。無駄なインプットは載せない方がいい、という前提で動いておく方が安全だと思います。
体感としても、長くなったエージェントは「手を抜く」
ここからは個人の主観ですが、Claude Code を含むコーディングエージェントは、コンテキストが膨らんでくると目に見えて挙動が雑になります。
最初の方では丁寧にファイルを開いて確認していたのに、後半になると「ここはこうしておきました」だけで実コードが薄かったりします。複数ファイルへの修正指示のうち1〜2ファイルしか触らずに完了報告してくる、というのもよくあるパターンです。
「サボる」と言いたくなる挙動ですが、別に擬人化しなくても context rot と Lost in the Middle で説明がつきます。注意が先頭と末尾に寄ってしまえば、中盤で渡したファイル内容や指示は薄れます。入力が長くなれば、その分だけ出力に割けるトークンも実質的に減っていきます。
逆に言うと、コンテキストが短く保たれている間のエージェントは、たぶん多くの人が最初に Claude Code を試して驚いたときの精度に近い動きを返してくれます。あの初速をどれだけ長く保てるか、と考えると、毎回先頭に詰め込まれるファイルは小さければ小さいほど得です。
構造として「全タスクの先頭に積まれる」のが問題
ここまでの話を踏まえると、CLAUDE.md と AGENTS.md の何が問題かが見えてきます。内容の良し悪し以前に、「全タスクの先頭に必ず差し込まれる」 という構造そのものが性能を落とす方向に効いているわけです。
- プロジェクトをまたいで共通化したいルールは、実はそれほど多くない
- 共通化したルールも、全タスクで使うわけではない
- それでも置けば毎回コンテキストの先頭に積まれ、その分だけ後段で使える注意とトークンが削られる
「全てのタスクに効くわけではないものを、全てのタスクの先頭に置く」というトレードオフが、研究と体感の両方から見て割に合わない、というのが現状の自分の評価です。
だから Skill に逃がす
具体的にどう運用しているか
CLAUDE.md をやめた代わりに、作業フロー単位で Skill を作って呼び出す運用に振り切っています。やっていることは大きく3つで、どれもコンテキストを膨らませない方向に揃えてあります。
作業タスクを細かく分ける
まず前提として、AI に投げる作業単位そのものを細かく切ります。「ブログを更新して」のような粗い指示ではなく、ネタ選定・執筆・レビュー・分析・リライトを別々のタスクとして扱う、というレベルです。
タスクを分けるほど、1回の呼び出しに必要な情報は少なくて済みます。Skill ごとに完結させてしまえば、別タスクの設定ファイルや指示書を毎回引きずる必要がなくなり、結果的にコンテキストの先頭はそのタスク専用のものだけで埋まります。
Skill には手順とルールをセットで書く
Skill ファイルには、達成したいゴールだけでなく「どの順番で何をやるか」という手順を明文化して書きます。
手順を書いておくと、AI は本当にその通りに動いてくれます。逆に、達成条件と原則だけ書いて手順を AI に組ませようとすると、毎回の対話で揺れてしまいます。その揺れを直すために会話が増え、結局コンテキストを食う方向に倒れていきます。
手順を固定した Skill は、毎回ほぼ同じトークン量で同じ結果に着地します。実行コストと品質のばらつきが揃ってくるので、運用に乗せやすくなるのも利点です。
ルール（やってはいけないこと・優先順位）も同じファイルに書きます。手順とルールがセットで載っていれば、Skill 呼び出し時にそれだけ読めば作業として完結します。
Skill を呼ぶことで得られる3つの利点
呼び出し型にしておくメリットは整理すると3つあります。
1つ目はコンテキスト消費が抑えられることです。CLAUDE.md のように毎回全タスクの先頭に積まれることがなく、その Skill を呼んだときにだけ読み込まれます。使わないタスクにとっては存在しないのと同じ扱いになり、無関係な指示で先頭領域を埋めずに済みます。
2つ目はスラッシュコマンドで直接起動できることです。やりたい作業が決まっているときは /write-post のように1コマンドで該当の Skill を呼び出せます。「これからブログを書きたいんだけど、こういうルールがあって……」と会話で前置きを再生する必要が無くなり、ここでも余計なトークンを払わずに済みます。
3つ目はスキルから別のスキルを呼べることです。1つの Skill が肥大化してきたら、内部から別の Skill を呼ぶ階層構造に切り替えます。自分の場合は /work が /write-post /review-post /analyze-posts を順に呼ぶ形にしています。
親 Skill は薄いオーケストレーターに留めて、各子 Skill だけが自分の手順を抱える形にする。そうしておけば、大きな作業でも実行中のコンテキストは「いま走っている子 Skill 分」だけに保てます。
共通化すべきルールは実はそれほど多くない
CLAUDE.md に書きたくなる「プロジェクト共通のルール」は、よく見直すと多くが「特定の作業フローの中のルール」だったりします。コードを書く作業を例に取れば、人間がやっているプロセスはたいてい次のように定型化されています。
- 計画を練る
- 設計を考える
- 実装する
- テストを書く
- リファクタリングする
- レビューする
このそれぞれは、いつ・どの順で・どこまで踏むかが決まっている作業です。だったら個別に Skill として切り出してしまい、必要なときに /plan /implement /review のように呼べばいい、という発想になります。
本当に「全タスク共通」と言えるのは、せいぜいリポジトリ名や言語固定くらいのものです。残りは作業フローに紐付くルールとして分解できる場合がほとんどです。
似たような運用をしている人たち
自分だけが特殊なことをしているわけではなくて、業務開発の現場でも近い思想で動いている例があるので並べておきます。
NTT データの事例[9]では、半年間の開発で73個のプロンプトファイル＋規約・補足ファイル群を作り、.github 配下だけで133個・約9,000行という規模になっています。注目したいのは設計思想で、「コンテキストウィンドウが埋まらないように、1ファイルをなるべく小さく作って、参照するファイルを最低限にしつつ、コンテキストに余裕がある状態を維持する」と明言されています。
さらに、開発者が直接プロンプトを入力して AI に仕事をさせることを禁止し、プロンプトファイルの修正か問題記述票の作成のいずれかしか許可しないという運用にしています。会話で揺らさず、定型化された呼び出しに集約する、というところまで含めて自分の感覚と近いです。
別方向だと、cureapp の「カスタムスラッシュコマンドはスキルに置き換えるべき」という記事[10]もあります。スキルは description がセッション開始時にだけ読み込まれ、本体は必要なときに展開される仕組みで、CLAUDE.md のように全部を先頭に積むよりコンテキスト効率が良い、という主張です。
Findy・ENECHANGE・kickflow など、カスタムスラッシュコマンドを業務に組み込んでいる Tech Blog[11] [12] [13] でも「1コマンド = 1責務」を原則にしているところは共通していて、責務を分けて呼び出し型にする発想は同時多発的に出てきている印象です。
CLAUDE.md を置く意味があるとしたら
逆向きに、「じゃあ全く要らないのか」と言われると、基本的には要らないです。「これを最初に読まないと AI が事故る」と言いたくなる類のルールも、Skill 側に書いておけば呼び出されたタイミングで読まれるので、CLAUDE.md に置く必要はありません。
唯一あるとすれば、Skill をまだ作っていない最初の数日です。とりあえずプロジェクトの前提だけ伝えたいときに CLAUDE.md を仮置きするのは、現実的な選択肢として残ります。
ただし、その状態は短く切り上げる前提で扱った方がいいと思います。仮置きのつもりで作った CLAUDE.md が居座ると、それ以降に作る Skill が「重複させたくない」「上書きしたくない」と気をつかう対象になり、結果として中途半端なルールがどちらにも残ります。早めに Skill に逃がして CLAUDE.md を空にする、くらいの方が運用としては綺麗です。
Lost in the Middle: How Language Models Use Long Contexts (Liu et al., TACL 2024) (2026-05-22 アクセス) ↩︎
Context Rot: How Increasing Input Tokens Impacts LLM Performance (Chroma, 2025-07) (2026-05-22 アクセス) ↩︎
Controlling the length of OpenAI model responses - OpenAI Help Center (2026-05-22 アクセス) ↩︎ ↩︎
Context windows - Claude API Docs (2026-05-22 アクセス) ↩︎ ↩︎
Prompt caching with Claude - Anthropic (2026-05-22 アクセス) ↩︎
Context Window & Compaction - Claude Code Docs (2026-05-22 アクセス) ↩︎
Managing context on the Claude Developer Platform (2026-05-22 アクセス) ↩︎
Effective context engineering for AI agents - Anthropic (2026-05-22 アクセス) ↩︎
設計書・コード・テストを全部AIに書かせて半年間開発してみたよ - NTT DATA Tech (2026-05-22 アクセス) ↩︎
カスタムスラッシュコマンドはスキルに置き換えるべき - cureapp (2026-05-22 アクセス) ↩︎
Claude Codeの活用事例: よく使うカスタムスラッシュコマンド5選 - Findy Tech Blog (2026-05-22 アクセス) ↩︎
Claude Codeカスタムスラッシュコマンド集 Part1 - ENECHANGE Developer Blog (2026-05-22 アクセス) ↩︎
kickflow で作って使っているカスタムスラッシュコマンドを紹介します - kickflow Tech Blog (2026-05-22 アクセス) ↩︎