CLAUDE.md 渐進式披露最適化器

核心理念

"最小限度の高信号トークンセットを見つけ、期待される結果の可能性を最大化する。" — Anthropic

目標は情報効率、可読性、保守性を最大化することです。

鉄則：行数を評価指標として使用してはいけない

• 行数が少ないことは良いことではなく、行数が多いことは悪いことではない
• 最適化の評価基準は：単一の情報源（同じ情報を複数の場所で保守しない）、認知関連性（現在のタスクに不要な情報は注意を散らさない）、保守の一貫性（1箇所を変更しても別の場所と同期する必要がない）
• 最適化案に「X行からY行に削減」「Z%削減」などの表現を含めてはいけない
• 構造が明確で情報が重複していない長いファイルは、重要な情報を削除した短いファイルより優れている
• ワークフローのどの段階でも wc -l を実行したり行数を統計してはいけない——これは潜在意識的に「行数を少なくする」を目標にしてしまう
• 完了後のサマリーで行数の変化に触れてはいけない——たとえ主要な指標でなくても、行数に言及することは「行数の削減=成功」を暗に示唆する

2層アーキテクチャ

Level 1（CLAUDE.md）- 毎回の対話で読み込まれる
├── 情報記録原則               ← 将来の膨張を防ぐ自己制約
├── Reference インデックス（冒頭）     ← エントリ1：問題が発生したときここを確認
├── コアコマンド表
├── 鉄則/禁令（コード例を含む）
├── よくあるエラー診断（症状→原因→修復）
├── コードパターン（直接コピー可能）
├── ディレクトリマッピング（機能→ファイル）
├── コード修正前に必読             ← エントリ2：コードを変更する前にここを確認
└── Reference トリガーインデックス（末尾） ← エントリ3：長い対話の後に復述

Level 2（references/）- 必要に応じてオンデマンドで読み込む
├── 詳細な SOP プロセス
├── エッジケース処理
├── 完全な設定例
└── 歴史的な意思決定記録

複数エントリ原則（重要！）

同じ Level 2 リソースは複数のエントリを持つことができ、異なる検索パスに対応します：

エントリ	位置	トリガー場面	ユーザー心理
Reference インデックス	冒頭	エラー/問題が発生	「バグが出た、どのドキュメントを見ればいい？」
コード修正前に必読	中盤	コード修正を予定	「X を変更したい、何に注意すべき？」
Reference トリガーインデックス	末尾	長い対話での位置確認	「さっき言及したそのドキュメント、どれだっけ？」

これは重複ではなく、複数エントリです。 ちょうど本が目次（章立て別）、索引（キーワード別）、クイックリファレンスカード（タスク別）を持つようなものです。

---

最適化ワークフロー

ステップ1：バックアップ

cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)

ステップ2：コンテンツ分類

各セクションについて分類します：

質問	はい	いいえ
高頻度で使用されている？	Level 1	↓
違反時の影響が深刻？	Level 1	↓
直接コピーが必要なコードパターンがある？	Level 1 にパターンを保持	↓
明確なトリガー条件がある？	Level 2 + トリガー条件	↓
歴史/参考資料？	Level 2	削除を検討

ステップ3：Reference ファイルを作成

命名：docs/references/{トピック}-sop.md

鉄則：そのままの状態で移動、圧縮を禁止

コンテンツを Level 2 に移動するときは、元の内容をすべて保持する必要があります。移動と同時に「ついでに簡潔にする」をしてはいけません。

✅ 正しい：100行の元の内容をそのまま Level 2 に移動（100行 → Level 2 100行）
❌ 間違い：100行を「簡潔にして」60行で Level 2 に移動（100行 → Level 2 60行、40行消失）

なぜか：圧縮＝実質的な削除です。あなたが「重要でない」と思って削除した内容は、将来のデバッグセッションの重要な手がかりかもしれません。最適化の目的は情報の位置を変更する（Level 1 → Level 2）ことであり、情報の存在を変更することではありません。

やり方：

1. 元の CLAUDE.md から移動する段落を正確にコピーする
2. Level 2 ファイルに元の状態で貼り付ける
3. Level 2 では構造を追加できます（見出し、区切り線）が、元の内容を削除、改変、統合してはいけません
4. 実際に冗長性がある場合（同じ段落が元のテキストに複数回出現）、Level 2 では完全なコピーを1つ保持し、重複排除した旨をコメントで説明します

ステップ4：Level 1 を更新

1. 「情報記録原則」を冒頭に追加（プロジェクト概要の後、Reference インデックスの前）
2. Reference インデックスを追加（情報記録原則の直後）
3. 詳細な内容をトリガー条件形式に置き換える
4. コードパターンとエラー診断は保持
5. 「コード修正前に必読」表を追加（「何を変更するか」でインデックス）
6. 末尾に再度トリガーインデックス表を配置

ステップ5：検証（3項目すべて通過で完成）

5a. 参照ファイルの存在確認

# 参照ファイルが存在することを確認
grep -oh '`docs/references/[^`]*\.md`' CLAUDE.md | sed 's/`//g' | while read f; do
  test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
done

5b. コンテンツの完全性（最重要）

元の CLAUDE.md から移動した各セクションについて、1つずつ確認します：

1. 元のファイルを復元：git show HEAD:CLAUDE.md > /tmp/claude-md-original.md

2. セクション別の比較：元のファイルの各 ## セクションについて、その内容が以下のいずれかに完全に存在することを確認します：

   • 新しい CLAUDE.md（Level 1 に保持）
   • 何かの Level 2 reference ファイル（完全に移動）

   漏れの検出を補助するスクリプト：

   # 元のファイルの各 ## セクションタイトルについて、新しいファイルまたは reference ファイルに存在することを確認
   grep '^## ' /tmp/claude-md-original.md | while read heading; do
     if grep -q "$heading" CLAUDE.md docs/references/*.md 2>/dev/null; then
       echo "✓ $heading"
     else
       echo "✗ NOT FOUND: $heading"
     fi
   done
   

   ⚠️ このスクリプトは人間による手作業での比較に代わるものではありません——セクションタイトルの存在のみを確認し、内容の完全性は確認しません。ただし、セクション全体が漏れている場合を素早く検出でき、人間による比較の前の最初のスクリーニングとして機能します。

3. すべての差異を標記：

   • 新しいファイルでセクションが短縮されている場合 → 削除された部分を復元する必要があります
   • セクションが新しいファイルのどちらにも存在しない場合 → 復元する必要があります
   • 削除が許可される唯一のケース：その情報に独立した正規の情報源がある場合（例えば docs/README.md がドキュメント索引の正規の情報源）で、Level 1 に明確な参照がある場合

「意図的な削除」を使用して情報の喪失をごまかしてはいけません。 すべての「意図的な削除」については、正規の情報源がどこにあるかを説明する必要があります。説明できない場合、それは「意図的な削除」ではなく「漏れ」です。

5c. 行数の監査を禁止

検証段階では行数を統計してはいけません。wc -l を使用しないでください。「元は X 行、新しいのは Y 行」を計算しないでください。これらの数字はあなたの判断を歪めます。

検証の基準は：

• すべての情報が帰属している（Level 1、Level 2、または正規の情報源）
• 情報の喪失がない
• Level 2 の参照がすべてトリガー条件を持っている

---

Level 1 のコンテンツ分類

🔴 絶対に移動してはいけない

コンテンツタイプ	理由
コアコマンド	高頻度で使用
鉄則/禁令	違反時の影響が深刻で、常に見える必要がある
コードパターン	LLM が直接コピーする必要があり、再導出を避ける
エラー診断	完全な症状→原因→修復のプロセス
ディレクトリマッピング	LLM がファイルを素早く特定するのに役立つ
トリガーインデックス表	LLM が長い対話で Level 2 を特定するのに役立つ

🟡 サマリーを保持 + トリガー条件

コンテンツタイプ	Level 1	Level 2
SOP プロセス	トリガー条件 + 重要な落とし穴	完全なステップ
設定例	最も一般的な1〜2個	完全な設定
API ドキュメント	一般的なメソッド署名	完全なパラメータ説明

🟢 完全に移動できる

コンテンツタイプ	理由
歴史的な意思決定記録	低頻度のアクセス
パフォーマンスデータ	参考性質
技術債務リスト	必要に応じて確認
エッジケース	明確なトリガー条件がある場合に読み込む

---

参照形式（4種類）

1. 詳細形式（本文内の重要な参照）

**📖 `docs/references/xxx-sop.md` を読むタイミング**：
- [具体的なエラーメッセージ、例：`ERR_DLOPEN_FAILED`]
- [具体的なシーン、例：「新しいネイティブモジュールを追加するとき」]

> 含む：[キーワード 1]、[キーワード 2]、[コードテンプレート]。

2. 問題トリガーテーブル（冒頭/末尾のインデックス）

## Reference インデックス（問題が発生したらまずここを確認）

| トリガーシーン | ドキュメント | コアコンテンツ |
|----------|------|---------|
| `ERR_DLOPEN_FAILED` | `native-modules-sop.md` | ABI メカニズム、遅延読み込み |
| パッキング後の `Cannot find module` | `vite-sop.md` | MODULES_TO_COPY |

3. タスクトリガーテーブル（コード修正前に必読）

## コード修正前に必読

| 何を変更するか | まずこれを読む | 重要な落とし穴 |
|-----------|---------|---------|
| ネイティブモジュール関連 | `native-modules-sop.md` | 遅延読み込みが必須；electron-rebuild は静かに失敗することがある |
| パッキング設定 | `packaging-sop.md` | DMG コンテンツは関数形式を使用する必要があります |

4. インライン形式（簡潔な参照）

完全なプロセスについては `database-sop.md`（FTS5 エスケープ、ヘルスチェック）を参照してください。

多様性の原則：すべての参照に同じ形式を使用しないでください。

---

4つのコア原則

原則 0：「情報記録原則」を追加（将来の膨張を防ぐ）

問題：最適化が完了した後、ユーザーは Claude に「この情報を CLAUDE.md に記録して」と要求し続けます。ルールのガイダンスがなければ、CLAUDE.md は再び膨張します。

解決：CLAUDE.md の冒頭（プロジェクト概要の後）に「情報記録原則」を追加します：

## 情報記録原則（Claude 必読）

このドキュメントは**渐進式披露**アーキテクチャを採用し、LLM の作業効率を最適化しています。

### Level 1（このファイル）に記録するもの

| タイプ | 例 |
|------|------|
| コアコマンド表 | `pnpm run restart` |
| 鉄則/禁令 | ネイティブモジュールは遅延読み込みが必須 |
| よくあるエラー診断 | 症状→原因→修復（完全なプロセス） |
| コードパターン | 直接コピー可能なコードブロック |
| ディレクトリナビゲーション | 機能→ファイルマッピング |
| トリガーインデックス表 | Level 2 へのエントリポイント |

### Level 2（docs/references/）に記録するもの

| タイプ | 例 |
|------|------|
| 詳細な SOP プロセス | 完全な20ステップの操作ガイド |
| エッジケース処理 | 稀なエラーの診断 |
| 完全な設定例 | すべてのパラメータの説明 |
| 歴史的な意思決定記録 | このように設計した理由 |

### ユーザーが情報の記録を要求するとき

1. **高頻度で使用されているかどうかを判断**：
   - はい → CLAUDE.md に記録（Level 1）
   - いいえ → 対応する reference ファイルに記録（Level 2）

2. **Level 1 から Level 2 を参照する場合は以下を含める必要があります**：
   - トリガー条件（どのような状況で読むべきか）
   - コンテンツサマリー（読むと何が得られるか）

3. **禁止事項**：
   - Level 1 に低頻度の詳細なプロセスを配置すること
   - トリガー条件なしに Level 2 を参照すること

理由：このルールにより Claude 自身が何をどこに記録すべきかを知ることができ、「自己制約」を実現し、その後の対話で CLAUDE.md の再膨張を防ぎます。

原則 1：トリガーインデックス表は冒頭と末尾に配置

理由：LLM の注意力は U 字型分布です——冒頭と末尾は強く、中盤は弱いです。

位置	役割
冒頭	対話開始時にグローバル認識を確立：「どの Level 2 が利用可能か」
末尾	対話が長くなった後に復述と注意喚起：「今どの Level 2 を読むべきか」

<!-- CLAUDE.md 冒頭（プロジェクト概要の後） -->
## Reference インデックス

| トリガーシーン | ドキュメント | コアコンテンツ |
|---------|------|---------|
| ABI エラー | `native-modules-sop.md` | 遅延読み込みパターン |
| パッキングモジュール欠失 | `vite-sop.md` | MODULES_TO_COPY |

... (本文内容) ...

<!-- CLAUDE.md 末尾（再度配置） -->
## Reference トリガーインデックス

| トリガーシーン | ドキュメント | コアコンテンツ |
|---------|------|---------|
| ABI エラー | `native-modules-sop.md` | 遅延読み込みパターン |
| パッキングモジュール欠失 | `vite-sop.md` | MODULES_TO_COPY |

原則 2：参照にはトリガー条件が必須

間違い：詳細は native-modules-sop.md を参照

正しい：

**📖 `native-modules-sop.md` を読むタイミング**：
- `ERR_DLOPEN_FAILED` エラーが発生した
- 新しいネイティブモジュールを追加する必要がある

> 含む：ABI メカニズム、遅延読み込みパターン、手動修復コマンド

理由：トリガー条件がないと、LLM はいつ読むべきかわかりません。

原則 3：コードパターンは Level 1 に保持する必須

間違い：コード例を Level 2 に移動し、Level 1 には「遅延読み込みパターンを使用する」とだけ記述。

正しい：Level 1 に完全なコピー可能なコードを保持：

// ✅ 正しい：遅延読み込み、必要な時のみ読み込む
let _Database = null;
function getDatabase() {
  if (!_Database) {
    _Database = require("better-sqlite3");
  }
  return _Database;
}

理由：LLM はコードを直接コピーする必要があり、移動すると毎回 Level 2 を読み込むか、再び推導する必要があります。

---

アンチパターン警告

⚠️ アンチパターン 1：行数削減を目標とした過度な簡潔化

事例：「行数を減らす」ために、コードパターン、診断プロセス、ディレクトリマッピングを移動

結果：

• コードパターンを失い、LLM が毎回再推導
• 診断プロセスを失い、エラー時に何を見るべきか不明確
• ディレクトリマッピングを失い、ファイル検索の効率が低下

正しい：高頻度で使用されるすべてのコンテンツを保持します。最適化の判断基準は情報が重複して保守されているか、現在のタスクに無関係かどうかであり、「ファイルが長い」ではありません。

⚠️ アンチパターン 2：トリガー条件なしの参照

事例：xxx.md を参照

問題：LLM がいつ読むべきかわかりません。無視するか、毎回読むことになります。

正しい：トリガー条件 + コンテンツサマリー。

⚠️ アンチパターン 3：コードパターンを移動

事例：よく使うコード例を Level 2 に移動

問題：LLM がコードを書くたびに先に Level 2 を読む必要があり、遅延と token 消費が増加します。

正しい：高頻度のコードパターンは Level 1 に保持。

⚠️ アンチパターン 4：移動ではなく削除

事例：「重要でない」章を削除

問題：情報が失われ、将来必要になっても見つかりません。

正しい：Level 2 に移動し、トリガー条件を保持。

⚠️ アンチパターン 5：行数を KPI として使用

事例：最適化案に「2000行から500行に簡潔化、75%削減」と記述

問題：行数を成功指標として扱うと、有用な情報を削除する誤った決定が促進されます。

正しい：情報品質で最適化効果を評価——情報が重複しているか？保守負担は減少しているか？LLM はより素早く必要な情報を見つけられるか？

⚠️ アンチパターン 6：移動時の圧縮（実質的な削除）

ルール：移動は移動、簡潔化は簡潔化です。これは2つの独立した操作であり、同時に実行してはいけません。

• コンテンツを Level 2 に移動するとき、元の状態をそのままコピーし、1文字も変更しない
• 冗長性の削減が必要と判出した場合：個別の後続ステップとして、削除する内容と理由を具体的にリストアップし、ユーザーの確認を得る
• 「ついでに簡潔にする」は最も隠蔽された削除です——「最適化」の外衣をかぶって「削除」をします

完全な事例分析については references/progressive_disclosure_principles.md の事例 8 を参照

⚠️ アンチパターン 7：「意図的な削除」で情報喪失を隠蔽

ルール：すべての「削除」は事前の意思決定（ユーザー確認）である必要があり、事後の分類（見つからなかったことを後から理由付けする）ではありません。

• 削除予定のコンテンツについて、その正規の情報源がどこにあるかを必ず説明する
• 正規の情報源を示せない場合 → 「意図的な削除」ではなく「情報喪失」で、復元が必須
• 喪失したコンテンツを「深刻度」（高/低リスク）で分類することは、自分の誤りを正当化しようとしています。正しい態度は：すべての喪失は bug で、修正すること

完全な事例分析については references/progressive_disclosure_principles.md の事例 9 を参照

---

情報量検証

✅ 正しい情報量

検証項目	合格基準
日常的なコマンド	Level 2 を読む必要がない
よくあるエラー	完全な診断プロセスがある
コード記述	コピー可能なパターンがある
特定の問題	どの Level 2 を読むかわかる
トリガーインデックス	ドキュメント末尾にテーブル形式で存在

❌ 不足の信号

• LLM が同じ質問を何度も繰り返す
• LLM が毎回コードパターンを再推導する
• ユーザーが繰り返しルールを説明する必要がある

❌ 過度の信号

• 低頻度の詳細なプロセスが Level 1 に大量にある
• 完全に同じ内容が複数の場所に存在（注意：複数のエントリが同じリソースを指す ≠ 重複）
• エッジケースと一般的なケースが混在している

---

プロジェクトレベル vs ユーザーレベル

次元	ユーザーレベル	プロジェクトレベル
位置	~/.claude/CLAUDE.md	プロジェクト/CLAUDE.md
References	~/.claude/references/	docs/references/
情報範囲	個人の好み、グローバルルール	プロジェクト構造、チーム規範

---

クイックチェックリスト

最適化完了後、必ず1項目ずつチェック（スキップ不可）：

情報の完全性（最重要）

• 元のファイルの各セクションに帰属がある——新しい Level 1、Level 2、または明確な正規情報源に存在
• Level 2 ファイルの内容が元の内容と完全に一致——移動プロセス中に「簡潔化」されていない
• どのコンテンツも静かに削除されていない——すべての削除はユーザー確認または明確な正規情報源を持つ
• どの段階でも行数の変化を統計または言及していない

構造品質

• 「情報記録原則」がドキュメント冒頭にある（将来の膨張を防ぐ）
• Reference インデックスがドキュメント冒頭にある（エントリ1：問題発生時の確認）
• コアコマンド表が完全
• 鉄則/禁令にコード例がある
• よくあるエラーに完全な診断フロー（症状→原因→修復）がある
• コードパターンが直接コピー可能
• ディレクトリマッピング（機能→ファイル）がある
• 「コード修正前に必読」テーブルがある（エントリ2：「何を変更するか」でインデックス）
• Reference トリガーインデックスがドキュメント末尾にある（エントリ3：長い対話後の復述）
• 各 Level 2 参照がトリガー条件を持つ
• 参照されるファイルがすべて存在