Tips & Tricks · Parhum Khoshbakht

私たちの CLAUDE.md は 162 行。何が入っていて、何を削ったか

プロジェクトルートの CLAUDE.md を 820 行から 162 行へ、ガードレールを 1 つも失わずに削減しました。コツはインラインのプロトコルをスキルのトリガー表で置き換え、ドメインルールをネストされたファイルとパススコープルールに移したことです。

あなたが知らない、リポジトリ内で最も高価なファイル

Claude Code を使っているなら、プロジェクトルートの CLAUDE.md はリポジトリ内で最も高価な単一ファイルです。ディスク容量のためではなく、1 バイト残らず、すべてのセッション開始時にコンテキストへ読み込まれ、遅延読み込みは存在しないからです。スキルは段階的に読み込まれます。MCP ツールは遅延できます。CLAUDE.md はそこに座り、常に読み込まれ、常にウィンドウに課金されます。

私たちのは 820 行でした。1 つのガードレールも失わずに 162 行へ削減しました。本記事は、何が抜け、何が残ったか、そして仕事をした 3 つのパターンの正確な記録です。

ヘッドラインの数値: 820 → 162 行、〜8,000 → 〜1,200 トークン、200K コンテキストウィンドウの 〜12% → 〜0.75%。

なぜ CLAUDE.md は専用記事に値するのか

広範なトークン最適化記事では、MCP Tool Search が単一で最大のレバーでした。CLAUDE.md は 2 番目です。大規模な Claude Code フレームワークの研究は、最適化されたルート設定がベースラインオーバーヘッドの 54〜62% 削減を達成することを報告しており、文書化されたアンチパターンの 1 つ — 2,800 行の CLAUDE.md — はセッションあたり概ね 62% のトークンを浪費していました。

理由はメカニズムにあります。階層のあらゆるレベルの CLAUDE.md コンテンツは無条件に読み込まれます。

  • エンタープライズポリシーファイル
  • プロジェクトルートの CLAUDE.md
  • ユーザーレベルの ~/.claude/CLAUDE.md
  • プロジェクトローカルのオーバーライド
  • @path/to/file 構文経由でインポートされたすべてのファイル (再帰的に最大 5 レベル深)

Claude Code がコンテキストの周囲で行う他のすべて — 段階的なスキル読み込み、MCP Tool Search、サブエージェント分離 — は、常時読み込みの税金を回避するように設計されています。CLAUDE.md は、すべてのターンで無条件に対価を払う唯一のものです。

ビフォー: 820 行、コンテキストの概ね 12%

オリジナルの CLAUDE.md は会社のハンドブックのように読めました。私たちが使うすべてのスキル、すべてのリリースゲートステップ、WordPress Coding Standards 設定のすべてのニュアンス、React コンポーネントのすべての命名規約、すべての管理アセットスコーピングルールを文書化していました。本物の有用な参考資料でした。同時に、その大半とは関係のないセッションも含めて、すべてのセッションに読み込まれていました。

その内訳の概算:

セクション行数概算トークン読み込み頻度は妥当か
ワークスペースマップとプロジェクト構造90900はい — どのセッションでも文脈となる
アーキテクチャと技術スタック60600はい
プライバシールール (譲れないもの)40400はい — 重要不変条件
スキルごとの説明 (30 件以上)1801,800いいえ — 個別スキルはオンデマンドで読み込まれる
ワークフローごとの詳細プロトコル2002,000いいえ — そのワークフロー中だけ必要
テスト標準の詳細1201,200いいえ — テスト記述セッションだけ関係
リリースゲートのウォークスルー80800いいえ — リリーススキルに住んでいる
トラブルシューティングのメモ50500いいえ — めったに必要ない

「いいえ」とマークされたものはすべて、ごく一部のセッションで利用可能であるためにすべてのセッションで税金を払っていました。これは概ね 6,300 トークンの浪費 — コンテキストウィンドウ全体の概ね 3% — を恒久的に占めていたことになります。

アフター: 162 行、概ね 0.75%

新しい CLAUDE.md は同じ表面領域を 3 つのパターンでカバーします。トリガー表、ネストされた CLAUDE.md ファイル、パススコープルールです。

パターン 1: スキルトリガー表

各スキルを段落で文書化する代わりに、〜30 件のスキル単位の説明を 1 つのルックアップテーブルで置き換えました。

## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| story, acceptance criteria | pm-story-write | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit, CVE | sec-audit-remediate | Security |
| wireframe, mockup | ux-design | UX |
| benchmark, performance | wp-performance | WP |

大規模フレームワークに関する研究は、このパターンが冗長なスキル単位の散文の 3,000 トークン以上に対して 〜800 トークンで済むと報告しています。Claude のルーティングは依然として正しく機能します。トリガーキーワードこそが実際にマッチさせるものであり、私たちが書いていた長文の「このスキルをいつ使い、いつ使わないか」というプローズはルーティングを助けず、コンテキストを満たすだけだったのです。

詳細な「いつ使い、いつ使わないか」のコンテンツはすべて個別の SKILL.md ファイル内に住み、Claude がそれにルーティングしたときだけ読み込まれます。トリガー表は索引、スキルは章です。

パターン 2: ドメインルールのためのネストされた CLAUDE.md ファイル

ほとんどの開発者が見落とす重要な特性: サブディレクトリ内のネストされた CLAUDE.md ファイルは遅延読み込みされるということです。これらは Claude がそのサブツリー内のファイルを読むときに初めてコンテキストへ入ります。

私たちのリポジトリレイアウトは現在こうなっています。

statnive-workflow/
├── CLAUDE.md                    # 162 lines — global only
├── statnive/
│   ├── CLAUDE.md                # PHP / WordPress plugin conventions
│   ├── src/
│   └── tests/
├── statnive-website/
│   └── CLAUDE.md                # Astro / MDX / frontend conventions
└── jaan-to/
    └── CLAUDE.md                # AI framework conventions

プラグイン用の PHP を書いているとき、statnive/CLAUDE.md が自動的に読み込まれ、WordPress Coding Standards のメモ、$wpdb->prepare() の強制ルール、管理アセットのスコーピングルールが持ち込まれます。MDX ブログコンテンツを書いているとき、statnive-website/CLAUDE.md が Astro 規約とハウススタイルメモとともに読み込まれます。互いに干渉しません。

このパターンで、ルートから「時々しか関係ない」コンテンツが概ね 2,200 トークン削減されました。

パターン 3: .claude/rules/ 内のパススコープルール

3 つ目のメカニズムは .claude/rules/ で、適用されるパスを宣言できる YAML フロントマター付きのルールファイルです。

---
paths: ["statnive-website/src/**/*.tsx", "statnive-website/src/**/*.astro"]
---
Use Tailwind utilities scoped under `#statnive-app`. Never import the default
Tailwind bundle — it restyles the WordPress admin chrome.

paths: フィールドのあるルールは条件付きで読み込まれます。マッチするファイルを Claude が扱っているときだけです。paths: フィールドのないルールは無条件に読み込まれるので、それらは厳密にひとにぎり (プライバシールール、セキュリティルール、コミット規約) に保ちます。

ルートの CLAUDE.md から、フレームワーク固有の規約のうち概ね 1,800 トークンを .claude/rules/ 配下のパススコープルールへ移しました。関連性があるときには確実に発火し、関連がなければコストはゼロです。

削除したアンチパターン: @-imports

オリジナルの CLAUDE.md には 3 つの @-imports がありました。

@jaan-to/docs/best-practices.md
@jaan-to/context/tech.md
@jaan-to/outputs/ROADMAP.md

整然として見えます。罠です。@ 構文は各ターゲットファイルの完全な内容を再帰的に、最大 5 レベル深まで、すべてのセッションで読み込みます。私たちの 3 つのインポートだけで、20 セッションに 1 回程度しかモデルが必要としないコンテンツのために、概ね 6,000 トークンの恒久的なオーバーヘッドを追加していました。

それぞれをポインターに置き換えました。

For architectural context see `jaan-to/context/tech.md`.
For the current roadmap see `jaan-to/outputs/ROADMAP.md`.

Claude は実際に必要なときに、これらのパスを Read ツールでオンデマンドに読みます。ベースラインコストはゼロ、実用的な結果は同じです。

ルートファイルにまだ住んでいるもの

削減後、162 行のルート CLAUDE.md には次のものが正確に含まれています。

セクション行数残った理由
プロダクト哲学 (研究からの 8 つの原則)28すべての判断を形作る — すべてのセッションに影響する必要がある
ワークスペースマップ18ひと目での方向感覚、どのセッションでも読み込まれる
プライバシールール (譲れないもの)16重要不変条件 — クッキー、生 IP、ソルト、SHA-256
管理アセットのスコーピングルール22過去に痛い目を見た、適用範囲が広い
コミットポリシー (co-authored-by トレーラーは禁止)8グローバルな git 規約
/simplify ワークフロールール18品質ゲートの強制
スキルトリガー表32〜30 件の冗長なスキル単位セクションを置換
主要パス (インポートではなくポインタ)20ドキュメントへの 1 行参照

それ以外はすべてネストされた CLAUDE.md、パススコープルール、または個別スキルの本体に移っています。

最適化しなかったもの

正直な注意点、シリーズの他の部分と同じパターンです。

  • ユーザーレベルの ~/.claude/CLAUDE.md は私たちの制御外。 エンジニアにはそれぞれの独自グローバル設定があり、それらはプロジェクトファイルの上に読み込まれます。研究はこれを隠れたオーバーヘッドの一般的な源として指摘しています。プロジェクトレベルのワークフローがちょうどそれをやっているのに、グローバル CLAUDE.md に「コミット前にテストを走らせることを忘れずに」と書かれていれば、シグナルを足さずにトークンが消費されます。チームメンバーには自分のものを監査するよう依頼しました。あなたのも見直す価値があるかもしれません。
  • ルート CLAUDE.md サイズの CI ゲートはまだない。 研究は、ルート CLAUDE.md と @-imports が 〜2,500 トークンを超えると PR を失敗させることを提案しています。私たちは /context のスポットチェックで強制しています。CI ゲートはロードマップにあります。
  • IMPORTANT と YOU MUST マーカーは誘惑的。 Anthropic は社内で CLAUDE.md ファイルを彼らのプロンプト改善器に通し、重要なルールに強調マーカーを使っています。私たちは控えめに使います。すべては恒久的なオーバーヘッドなので、プライバシールール (クッキーなし、生 IP なし) とコミットポリシー (co-authored-by トレーラーなし) のために予約しています。

飛ばせない計測ステップ

自分の CLAUDE.md を監査するなら、唯一重要なコマンドは /context です。新しいセッションのまさに最初、プロンプト前に実行してください。コンテキスト使用量がソース別に分解されます。システムプロンプト、ツール、メモリ (これが CLAUDE.md)、スキルメタデータ、MCP ツールスキーマです。

200K ウィンドウのセッションで私たちが目指す数値:

ソース目標ハードキャップ
ルート CLAUDE.md + スコープなしルール≤ 1,500 トークン2,500
スキルメタデータ≤ 2,500 トークン5,000
MCP ツールスキーマ (Tool Search 利用)≤ 3,000 トークン8,000
フック標準出力 (SessionStart、UserPromptSubmit)0 トークンフックあたり 300

/context がこれらのいずれかを 〜50% 以上超過しているなら、私たちが抱えていたのと同じ問題があります。修正は上記の 3 つのパターン + MCP Tool Search です。

なぜこれが Statnive の運用者にとって重要なのか

私たちの CLAUDE.md は GitHub の Statnive リポジトリで公開しています。テストパイプラインを公開しているのと同じ理由です。引き締まったルート設定はセッションを高速にし、実行を安価にし、「常に利用可能、めったに必要ない」参考資料に溺れる代わりに、本当に重要なものを実際に読むモデルを意味します。その効率性は、私たちのユーザーが気にかけるのと同じものへ複合します。頻繁に出荷され、5KB トラッカー予算を維持するプラグインです。

Statnive を試す

トークン予算をパフォーマンス予算と同じくらい真剣に扱うチームによって構築された、プライバシー重視の WordPress アナリティクス。WordPress.org から Statnive を無料インストール — データはサーバーに留まり、エンジニアリングプラクティスは誰でも監査できるよう GitHub に留まります。

Statnive を無料で入手