Claude Code や Codex などの AI CLI を毎日使っていると、~/.claude/CLAUDE.md みたいなグローバル設定が少しずつ育っていきます。tips が増え、失敗の教訓が加わり、気付けばそこそこの厚さになっている。今回、それを見直す機会があったので、その時に考えたことをまとめておきます。
きっかけは、note でこんな記事を読んだことでした。「トークン消費を抑える工夫」というテーマで、その中に「200 行を超える CLAUDE.md は、コンテキスト消費が増えて指示遵守率が下がる可能性がある」という一節があった。
自分の CLAUDE.md は当時 251 行あった。素直に受け取れば「削らなきゃ」となる場面です。ただ、この 200 という数字、本当なのだろうか。ちょっと引っかかった。
その 200 行、根拠あるやつ？
Anthropic 公式のドキュメントを探しても、CLAUDE.md の推奨サイズについて「200 行」という閾値は書かれていません。記事の中でも「〜可能性がある」という留保付きで、断定形ではない。個人の観察ベース。
実際に自分の環境で計算してみます。
- CLAUDE.md 251 行 = 約 13KB ≈ 6000〜8000 トークン
- Claude Opus 4.7 のコンテキスト = 1,000,000 トークン
- 占有率 = 0.6〜0.8%
さらに Claude Code は prompt caching が効くので、毎ターンの CLAUDE.md は基本キャッシュヒットします。実費はほぼ 0。1M コンテキストの入口に数千トークン置いてあっても、実害は測定できるレベルではないのが今の世代の Claude です。
つまり、「200 行を超えると劣化する」という主張は、Claude 4.7 で見る限り成立しない。数字自体は権威ある基準ではなく、コミュニティで広まった経験則、というくらいの話でした。
上の 1 枚に、今回の判定の骨子を並べています。数字の閾値ではなく、判断軸を置き換える話が中心です。
じゃあ、なぜ「常時ロードを軽く」と言われるのか
数字が根拠を持たないなら記事の主張自体が的外れかというと、そうではないと思います。行数はダミー変数で、本当の敵は別にある。書きながら気付いたのは、この 3 つ。
- トリガーの埋没。 毎回効かせたいルールが、その時だけ関係するルールに埋もれると、モデルが該当ルールを想起できなくなる。信号対雑音比の問題です
- 矛盾ルールの共存。 長くなるほど、過去に足したルール同士が微妙に衝突する確率が上がる。モデルはどちらかを黙って選びます
- 人間側のメンテ負荷。 251 行は AI ではなく、書いた本人が全体を把握しきれなくなる閾値
これで判断軸を置き換えることにしました。「行数」ではなく「発火頻度」で仕分ける。
| 発火頻度 | 置き場所 |
|---|---|
| 毎ターン必ず効かせたい（言語・シェル選択・ツール使い分け原則） | CLAUDE.md 本体 |
| 特定タスク時のみ効かせたい（バグ調査・md 作成・secrets-scan） |
guides/ に切り出しトリガー 1 行 |
| 特定ドメイン話題時のみ（家族・kb・家系） | 条件付き Read（@import しない） |
これで結果的にサイズは減るかもしれない。でも動機は「200 行以下にする」ではなく「常時発火する内容だけを残す」です。順序が違うと、削り過ぎて重要な指針まで捨てる事故が起きます。
実際にやってみたら 251 → 114 行
上の物差しで CLAUDE.md 全 251 行を眺め直しました。8 個のガイドファイルに切り出し、CLAUDE.md 本体はトリガー行だけに整理。結果として 114 行、56% 削減。
上のように、常時発火は本体に、特定タスク時発火はガイドに、というシンプルな仕分けです。中身が消えたわけではなくて、参照タイミングが変わっただけ。
面白かったのは、「シェル選択の 6 項目」を全部残したことです。行数ダイエットの発想なら削りたくなる長い節ですが、これは実質「毎ツール呼び出しで発火」する規則。Windows PowerShell と Bash の使い分けを毎回頭にちらつかせておかないと、.ps1 を Bash に投げてエラーになる過去の失敗を繰り返す。発火頻度で見ると「絶対に残す側」なんです。
Skill の description も 30% 削れた
同じ考えで、~/.claude/skills/*/SKILL.md の frontmatter description を見直しました。この description は毎ターン Available skills 一覧としてコンテキストに載る、本当の意味での常時ロード対象です。
- 29 個の skill、合計 10,368 文字
- モードや設計思想の詳細は本文に既にある。description からは削れる
- 起動語（
「〜」「〜」）はそのまま残す。ここが呼び出しトリガーだから
結果、合計 7,199 文字（-31%）。長かった project-init は 718 文字が 250 文字になりました。
Skill の棚卸しは「まだ判断できない」
見直しで最後に残ったのが、そもそも 29 個も skill が要るのか、という問題でした。使っていない skill を退避すれば description 分がまるごと浮く。
ここで詰まりました。「どれを退避するか」を自分で決めようとすると、頭で「たぶん使ってない」と思っている skill と、実際に使ってる skill が違うかもしれない。感覚で切ると、あとで「あれ、これ意外と便利だったのに」となる。
なので、感覚で決めるのをやめて、データを取ることにしました。
各 SKILL.md の本文 1 行目に、こんな指示を挿入します。
> **起動時に必ず実行**（棚卸し用ログ・1 行だけ）: `pwsh -NoProfile -File $env:USERPROFILE\.claude\scripts\log-skill-usage.ps1 <skill-name>`
呼び出された AI がこの 1 行に従ってログを 1 行追記する。CSV に timestamp / skill / cli を残していく。1 ヶ月経ったら Import-Csv | Group-Object skill で集計する、それだけの仕組みです。
図のように、フックみたいな CLI 別の層を挟まず、SKILL.md 自体を発火点にしています。嬉しいのは、この仕込みが CLI 非依存で動くこと。Claude Code / Codex / Cursor / opencode、どれから起動しても SKILL.md を読んで従うのは AI 側なので、フックが要らない。
最初、Claude Code の PostToolUse フックを提案したら「他の AI エージェント使った時に補足できないよね？」と指摘を受けて、そこから設計を組み直しました。バーチャル層で見張るより、SKILL.md 自体を発火点にする方が自然でした。
学んだこと
3 つあります。
- 数字の閾値は疑ってから採用する。「200 行」に限らず、SNS で広まっている数字ルールは、その世代のモデル・その人の環境でしか成立しないことがある。自分の環境で確かめてから物差しにするのが安全です
- 削る動機を書き換える。目的が「行数を減らす」だと、削り過ぎて重要な指針まで消してしまう。「毎ターン発火だけ残す」と言い換えると、判断がぶれない
- 感覚で決められない棚卸しはデータに委ねる。頭の中の「使ってない気がする」は当てにならないので、1 ヶ月の実測に任せる方が失敗が少ないです
盲目的に流行りの数字に合わせるのではなく、その数字が何を代理して指しているかを一度考える。物差しの当て直しを、これからも習慣にしていきます。
※ ヘッダー画像とインフォグラフィックは AI（画像生成）で作成しています。
書いた人: ishizakahiroshi
群馬の北部で、保護猫2匹と暮らす、在宅エンジニア（何でも屋）
https://ishizakahiroshi.github.io/
https://github.com/ishizakahiroshi
X（業務委託・各種相談はこちら）：
https://x.com/ishizakahiroshi
バックエンド・インフラ・AI連携まわりで、業務委託のご相談を受け付けています。フルリモートです。スポットや週2〜3時間からでも歓迎で、いろんな案件に携われたらうれしいです。こんな相談、歓迎です。