肥大化した CLAUDE.md を 269行から155行に削った

清水亮さんが「CLAUDE.md はシンプルなほど効く」という趣旨のことを書いていた。その記事をいま探したら見つからない。消えたのかもしれない。ただ言っていたことは頭に残っていて、自分のブログ運用リポジトリの CLAUDE.md を削ってみた。

269行 → 155行。文字数で約4割減。

先に結論を言うと、毎セッションで読み込む量ははっきり減った。ただ「AIが賢くなったか」の体感は、まだ語れない。削った直後の「なんとなくスッキリした」は効果ではないからだ。まず、何がどれだけ減ったのかを数えるところから始める。

なぜ CLAUDE.md は太るのか

運用ルールを思いつくたびに、ここへ書き足していた。

写真日記の文体。 X投稿の文字数計算式。テック記事を書くときの段取り。アイキャッチを SVG から作る手順。記事末尾の記名フォーマット。

どれも「忘れると事故る」から書いた。気づけば269行になっていた。

このファイルは毎セッションの冒頭で丸ごと読み込まれる。記事を1本書くだけのときも、写真日記の手順もアイキャッチの手順も毎回読まされていた。使わない知識を、起動するたびに全部めくっている状態。

削る基準

Anthropic が2026年5月に出した大規模コードベース向けのベストプラクティスに、「CLAUDE.md に書くべきでないもの」の整理がある。これは別記事にまとめた。

理屈は分かっていた。問題は、自分の手元のファイルでどう線を引くか。

基準はひとつにした。

この行を消したら、AIが間違えるか?

間違えるなら残す。間違えないなら、それは指示ではなく説明書だ。別の場所に出す。

実際にやった3つのこと

1. 詳細ワークフローはスキルへ追い出した

写真日記の作り方、X投稿文の組み立て、記事執筆の段取り。これらは「やるとき」にしか要らない。

Claude Code のスキルに移して、CLAUDE.md には1行の対応表だけ残した。

やりたいこと	スキル
記事を書く	`article`
写真日記を書く	`diary`
X 投稿文を作る	`x-post`
画像を生成する	`comfyui-image-gen`

たとえば写真日記の書き方。「基本はですます調だが素の口調が混ざる」「猫への愛情がにじむ」といった文体ルールや、ファイル名の連番規約が、以前は本体に30行ほど居座っていた。これを diary スキルに移し、本体の表からは「写真日記を書く → diary」の1行で指すだけにした。

スキルはオンデマンドで開く。記事を書くときだけ article が読まれる。写真日記のときだけ diary が読まれる。全部を毎回抱えておく必要がなくなった。

2. ディレクトリ固有のルールは分離した

記事ディレクトリの構造、front matter、アイキャッチの種類別ルール。これは site/content/post/ を触るときにしか関係ない。

site/content/post/CLAUDE.md（70行）に切り出した。 Claude Code はサブディレクトリの CLAUDE.md を、そのディレクトリで作業するときに読む。記事を触らないセッションでは、この70行は視界に入らない。

3. .claudeignore を新設した

CLAUDE.md 本体の話ではないが、同じ「ノイズを減らす」作業。

うちのリポジトリは Hugo のビルド出力で数万ファイルある。 grep や glob がそこを舐めると遅いし、関係ないヒットも増える。

site/public/、node_modules/、28GB の WordPress バックアップなどを .claudeignore で除外した。探索の対象を、自分が編集するファイルだけに絞った。

効果を実測する

項目	Before	After	差分
ルート `CLAUDE.md` 行数	269	155	−114
ルート `CLAUDE.md` 文字数	7,160	4,341	−2,819（約40%減）

毎セッションの冒頭で読む量が、4割減った。

追い出した約2,800字は消したわけではない。スキルと site/content/post/CLAUDE.md（70行 / 2,082字）に移して、必要なときだけ開く形にした。「捨てた」のではなく「常時ロードから外した」が正しい。

数字でははっきり減った。ここまでは事実。

まだ分からないこと

正直に書くと、「AIの返答そのものが良くなったか」はまだ分からない。

削ったのは最近で、体感を語れるほど使い込んでいない。コンテキストが軽くなれば指示の取りこぼしは減るはず、というのは理屈であって、まだ自分の手元のデータではない。

ここは数ヶ月使って、また書く。減らした効果を本当に確かめるのは、ここからだ。

削ってみて思ったこと

CLAUDE.md は説明書ではなかった。「忘れたら事故るチェックリスト」に近い。

説明書は厚いほど親切だが、チェックリストは短いほど見る。毎回読まれるファイルだからこそ、削ることが足すことになる。

そういう種類のファイルだと、削って初めて分かった。