Claude CodeのCLAUDE.md肥大化を解消【403行→176行】
AIエージェント（Claude Code）を毎日使っていると、作業のたびに「これも指示書に書いておこう」と、ルールや手順を書き足していくことがあります。便利な反面、放っておくと指示書自体がどんどん膨れ上がっていきます。この記事では、実際に403行まで肥大化した指示書を176行（約56%減）まで圧縮した実例を、具体的な手順とあわせて紹介します。
AIエージェントの「指示書」とは何か
Claude Codeのようなコーディング系AIエージェントには、セッションを開始するたびに自動的に読み込まれる指示書（一般的に「CLAUDE.md」や「AGENTS.md」と呼ばれるファイル）を用意できます。ここに、作業の進め方・守ってほしいルール・過去の失敗から学んだ注意点などを書いておくことで、毎回同じ説明を口頭で繰り返さずに済みます。
前回の記事では、この指示書とは別に、Obsidian（ノートアプリ）を使った「第二の脳」というナレッジベースをAIエージェントに参照させている話を書きました。指示書は「毎回必ず読ませる短いルール集」、第二の脳は「必要な時に検索して参照する蓄積型の知識」という役割分担です。
今回紹介するのは、その「毎回必ず読ませる」はずの指示書自体が、気づけば長大になってしまっていた、という実例です。
何が起きていたか：403行まで肥大化した指示書
きっかけは、「最近コンテキストが溜まってきている気がする」という感覚でした。実際に指示書のファイルを確認してみると、403行という分量になっていました。
内容を見返すと、単純なルールだけでなく、特定の作業（たとえば「書籍を1冊作るときの手順」のような、Phase0からPhase9まで続く詳細な作業ステップ）まで、すべて同じ指示書の中にベタ書きされていました。
毎回のセッションの最初に、この403行を全部読み込ませる運用になっていたため、AIエージェントが本当に必要な概要にたどり着くまでに、多くの行数を経由する必要がある状態になっていたと考えられます。
なぜ膨れ上がってしまったのか
- 新しいルールや注意点を思いつくたびに、既存の指示書へ追記していった
- 「一度だけ使う手順」も「毎回使うルール」も、区別せず同じファイルに書いていた
- ファイルが1つにまとまっている安心感から、分割・整理を後回しにしていた
対処法：詳細手順を「スキル」という別ファイルへ分離
Claude Codeには「スキル」という仕組みがあります。特定の作業のときだけAIエージェントが自動で見つけて読み込む、専用の手順書を別ファイルとして持たせられる機能です。
そこで、指示書の中に埋め込まれていた「特定の作業のときにしか使わない長い手順」を、それぞれ専用のスキルファイルへ切り出すことにしました。
実際にやったこと
1. 指示書の中身を見返し、「毎回必ず読ませたいルール（概要・NGワード・確認プロセスなど）」と「特定の作業のときだけ必要な詳細手順」を仕分けする
2. 詳細手順の部分（今回は2つの作業ルーティンのPhase0〜Phase9の手順）を、それぞれ独立したスキルファイルとして新規作成する
3. 複数箇所に重複して書かれていたルール（今回は画像生成のファイル命名規則や事前準備の手順）を、既存の関連スキルに統合する
4. 指示書側には、「どのスキルを、どんな作業のときに使うか」という概要だけを残す
5. 変更後の指示書とスキルファイルを実際に読み込ませ、行数と動作の両方を確認する
この作業は1回のセッションで完結し、最終的に6ファイルの変更（追加約337行・削除約529行）としてまとめてコミットしました。
結果：403行→176行（約56%減）
この整理の結果、毎回読み込ませる指示書は403行から176行まで圧縮できました。割合にすると約56%減です。
詳細な手順そのものが消えたわけではなく、スキルファイル側にそのまま残っているので、必要なときにはこれまでと同じ精度で参照できます。変わったのは、「普段の作業では概要だけを読み込み、詳細が必要になったタイミングでスキル側を呼び出す」という順番だけです。
体感として大きかったのは、指示書自体の見通しが良くなったことです。新しいルールを追記するときも、「これは概要に書くべきか、詳細手順としてスキル側に書くべきか」を自然と考えるようになりました。
実際にやってみて気づいた注意点
分離作業を進める中で、1つ見落としそうになった点がありました。「スキルを説明文だけで自動的に見つけて読み込む」という仕組みは、すべてのAIツールに標準で備わっているわけではないということです。
同じ指示書を複数のAIツール（今回のケースでは、コーディング用に併用しているもう一つのCLIツール）にも読ませている場合、片方には自動読み込みの仕組みがあっても、もう片方には無いことがあります。「このスキルを見て」と指示書に一文書いても、そのツールが自動でファイルを探しに行ってくれるとは限りません。
この場合は、そのツール向けの指示書だけに、「このファイルを直接参照してください」という一文と、対象ファイルの場所を明記する対応を追加しました。複数のAIツールを併用しているときは、片方の環境で当たり前にできることが、もう片方では同じようにはいかない場合がある、という点は覚えておくとよさそうです。
よくある質問（FAQ）
Q. 指示書はどれくらいの分量が適正ですか？
A. 明確な基準があるわけではありませんが、目安として「毎回読ませても負担にならない分量か」を基準にしています。今回は403行が「多すぎる」と感じた分量でした。
Q. スキルに分離すると、精度は落ちませんか？
A. 詳細手順の中身自体は変えていないので、実際に使う場面では同じ手順を参照できます。変わるのは「常に全部読むか、必要な時だけ読むか」というタイミングだけです。
Q. どのくらいの頻度で指示書を見直すべきですか？
A. まだ確立したルーティンはありませんが、今週の後半では「見直しルール自体を作ったのに一度も実行していなかった」という失敗談も紹介する予定です。
まとめ
AIエージェントに毎回読み込ませる指示書は、便利だからと書き足しているうちに、気づかないうちに肥大化していきます。今回は、特定の作業でしか使わない詳細手順を「スキル」という別ファイルへ切り出すことで、403行から176行（約56%減）まで圧縮できました。「毎回読ませるもの」と「必要な時だけ読ませるもの」を分ける、という考え方は、AIエージェントの運用を整理するうえで参考になるはずです。
