目次
Claude Code を本格的に触り始めてしばらく経つのですが、いろいろ試した結果、リポジトリのルートに CLAUDE.md も AGENTS.md も置かない運用に落ち着きました。最初は「プロジェクトのお作法は最初に全部渡しておくべき」と思っていたんですが、いざ使ってみると逆効果になる場面が多かったというのが正直なところです。
CLAUDE.mdはAIの性能を落とす
結論から書くと、CLAUDE.md や AGENTS.md を置かない理由はシンプルで、無駄なコンテキストが入り込んで AI の性能が落ちるのが嫌だからです。
性能が落ちる理由は2つに分けると見えやすいです。1つはそもそも AI に与える入力が長くなるほど出力品質が下がるという性質。もう1つは、CLAUDE.md の構造のせいで、目の前のタスクに関係ない指示まで毎回先頭に積まれてしまうことです。
コンテキストが増えるとAIの性能が落ちる
LLM や AI エージェントは、入力が長くなるほど出力精度が落ちるという性質を構造的に抱えています。
「Lost in the Middle」「Context Rot」のような研究では、長い入力の中央に置いた情報ほど読まれにくいことや、入力トークンが増えるほど出力品質が劣化することが実測されています。
API の作りとしても、コンテキストウィンドウは input と output の合算予算なので、input を太らせるほど1回の応答で書ける量が物理的に削られていきます。詳細は別記事にまとめました。
CLAUDE.mdには使われない指示が必ず混ざる
ここまでの話を踏まえると、CLAUDE.md と AGENTS.md の何が問題かが見えてきます。内容の良し悪し以前に、「全タスクの先頭に必ず差し込まれる」 という構造そのものが性能を落とす方向に効いているわけです。
- プロジェクトをまたいで共通化したいルールは、実はそれほど多くない
- 共通化したルールも、全タスクで使うわけではない
- それでも置けば毎回コンテキストの先頭に積まれ、その分だけ後段で使える注意とトークンが削られる
「全てのタスクに効くわけではないものを、全てのタスクの先頭に置く」というトレードオフが、研究と体感の両方から見て割に合わない、というのが現状の自分の評価です。
CLAUDE.mdは全部 Skill に分解する
CLAUDE.md をやめた代わりに、作業フロー単位で Skill を作って呼び出す運用に振り切っています。やっていることは大きく3つで、どれもコンテキストを膨らませない方向に揃えてあります。
作業タスクを細かく分ける
まず前提として、AI に投げる作業単位そのものを細かく切ります。「ブログを更新して」のような粗い指示ではなく、ネタ選定・執筆・レビュー・分析・リライトを別々のタスクとして扱う、というレベルです。
タスクを分けるほど、1回の呼び出しに必要な情報は少なくて済みます。
Skill ごとに完結させてしまえば、別タスクの設定ファイルや指示書を毎回引きずる必要がなくなり、結果的にコンテキストの先頭はそのタスク専用のものだけで埋まります。
Skillには手順とルールをセットで書く
Skill ファイルには、達成したいゴールだけでなく「どの順番で何をやるか」という手順を明文化して書きます。
手順を書いておくと、AI は本当にその通りに動いてくれます。逆に、達成条件と原則だけ書いて手順を AI に組ませようとすると、毎回の対話で揺れてしまいます。
その揺れを直すために会話が増え、結局コンテキストを食う方向に倒れていきます。
手順を固定した Skill は、毎回ほぼ同じトークン量で同じ結果に着地します。実行コストと品質のばらつきが揃ってくるので、運用に乗せやすくなるのも利点です。
ルール（やってはいけないこと・優先順位）も同じファイルに書きます。手順とルールがセットで載っていれば、Skill 呼び出し時にそれだけ読めば作業として完結します。
Skillならコンテキスト消費を抑えられる
ここまでに挙げた「タスクを細かく分ける」「手順とルールをSkillに書く」を実際に動かすと、CLAUDE.md と比べてコンテキスト消費がはっきり下がります。
抑えられる仕組みを3つに分けて整理します。
必要なときだけ読み込まれる
CLAUDE.md のように毎回全タスクの先頭に積まれることがなく、その Skill を呼んだときにだけ読み込まれます。
使わないタスクにとっては存在しないのと同じ扱いになり、無関係な指示で先頭領域を埋めずに済みます。
スラッシュコマンドで前置きを省ける
やりたい作業が決まっているときは /write-post のように1コマンドで該当の Skill を呼び出せます。
「これからブログを書きたいんだけど、こういうルールがあって……」と会話で前置きを再生する必要がなくなり、ここでも余計なトークンを払わずに済みます。
親Skillから子Skillを呼んで階層化できる
1つの Skill が肥大化してきたら、内部から別の Skill を呼ぶ階層構造に切り替えます。自分の場合は /work が /write-post /review-post /analyze-posts を順に呼ぶ形にしています。
親 Skill は薄いオーケストレーターに留めて、各子 Skill だけが自分の手順を抱える形にする。そうしておけば、大きな作業でも実行中のコンテキストは「いま走っている子 Skill 分」だけに保てます。
共通化すべきルールは実はそれほど多くない
CLAUDE.md に書きたくなる「プロジェクト共通のルール」は、よく見直すと多くが「特定の作業フローの中のルール」だったりします。
コードを書く作業を例に取れば、人間がやっているプロセスはたいてい次のように定型化されています。
- 計画を練る
- 設計を考える
- 実装する
- テストを書く
- リファクタリングする
- レビューする
このそれぞれは、いつ・どの順で・どこまで踏むかが決まっている作業です。だったら個別に Skill として切り出してしまい、必要なときに /plan /implement /review のように呼べばいい、という発想になります。
本当に「全タスク共通」と言えるのは、せいぜいリポジトリ名や言語固定くらいのものです。残りは作業フローに紐付くルールとして分解できる場合がほとんどです。
似たような運用をしている人たち
自分だけが特殊なことをしているわけではなくて、業務開発の現場でも近い思想で動いている例があるので並べておきます。
NTT データの事例[1]では、半年間の開発で73個のプロンプトファイル＋規約・補足ファイル群を作り、.github 配下だけで133個・約9,000行という規模になっています。
注目したいのは設計思想で、「コンテキストウィンドウが埋まらないように、1ファイルをなるべく小さく作って、参照するファイルを最低限にしつつ、コンテキストに余裕がある状態を維持する」と明言されています。
さらに、開発者が直接プロンプトを入力して AI に仕事をさせることを禁止し、プロンプトファイルの修正か問題記述票の作成のいずれかしか許可しないという運用にしています。
会話で揺らさず、定型化された呼び出しに集約する、というところまで含めて自分の感覚と近いです。
別方向だと、cureapp の「カスタムスラッシュコマンドはスキルに置き換えるべき」という記事[2]もあります。
スキルは description がセッション開始時にだけ読み込まれ、本体は必要なときに展開される仕組みで、CLAUDE.md のように全部を先頭に積むよりコンテキスト効率が良い、という主張です。
Findy・ENECHANGE・kickflow など、カスタムスラッシュコマンドを業務に組み込んでいる Tech Blog[3] [4] [5] でも「1コマンド = 1責務」を原則にしているところは共通しています。
責務を分けて呼び出し型にする発想は同時多発的に出てきている印象です。
CLAUDE.mdは基本使わない
「じゃあ全く要らないのか」と言われると、基本的には要らないです。
「これを最初に読まないと AI が事故る」と言いたくなる類のルールも、Skill 側に書いておけば呼び出されたタイミングで読まれるので、CLAUDE.md に置く必要はありません。
唯一あるとすれば、Skill をまだ作っていない最初の数日です。とりあえずプロジェクトの前提だけ伝えたいときに CLAUDE.md を仮置きするのは、現実的な選択肢として残ります。
ただし、その状態は短く切り上げる前提で扱った方がいいと思います。
仮置きのつもりで作った CLAUDE.md が居座ると、それ以降に作る Skill が「重複させたくない」「上書きしたくない」と気をつかう対象になり、結果として中途半端なルールがどちらにも残ります。
早めに Skill に逃がして CLAUDE.md を空にする、くらいの方が運用としては綺麗です。
設計書・コード・テストを全部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 アクセス) ↩︎