claude-md-progressive-disclosurer

CLAUDE.md の段階的開示の最適化

機能を維持しながらコンテキストのオーバーヘッドを減らすために、ユーザーの CLAUDE.md ファイルを分析して最適化します。

クイックスタート

1. バックアップ：まず元のファイルをバックアップします
2. 監査：現在の状態を確認します（すべてのセクションを行数とともに一覧表示）
3. 分類：以下の基準を使って各セクションを分類します
4. 提案：変更前後の比較表を添えて、最適化案を提示します
5. 確認：実行前に情報の完全性チェックリストを確認します
6. 実行：承認された変更を適用します
7. テスト：移動した内容を引き続き見つけられることを確認します

セクションの分類

各セクションを分析し、次のように分類します。

カテゴリー	基準	対応
CLAUDE.md に残す	基本原則、短いルール（10 行未満）、頻繁に必要となる情報	そのまま残す
references/ に移動	詳細な手順、コード例、トラブルシューティングガイド	~/.claude/references/<name>.md を作成する
スキルとして抽出	再利用可能なワークフロー、スクリプト、ドメイン固有の知識	スキルリポジトリにスキルを作成する
削除	既存のスキルと重複している、古くなっている、または不要	確認後に削除する

サイズに関するガイドラインの例外

セクションが 50 行を超えていても、次のいずれかに該当する場合は、CLAUDE.md に残してください。

例外	理由	例
安全性に関わる	忘れた場合の影響が重大である	デプロイ手順、「main に force push しない」
高頻度で参照される	ほとんどの会話で参照される	基本的な開発パターン、よく使うコマンド
違反しやすい	表示されていないと Claude が無視しがちである	コードスタイルのルール、権限要件
セキュリティ上重要	常に適用する必要がある	本番環境へのアクセス制限、データ取り扱いルール

経験則：そのルールを忘れることで、本番環境のインシデント、データ損失、またはセキュリティ侵害が発生するおそれがある場合は、長さにかかわらず見える場所に残してください。

最適化ワークフロー

ステップ 0：元のファイルをバックアップする

重要：変更を加える前に、必ずバックアップを作成してください。

# Create timestamped backup
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)

# For project-level CLAUDE.md
cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)

最適化後に問題が見つかった場合：

# Restore from backup
cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md

ステップ 1：現在の状態を監査する

Task Progress:
- [ ] Create backup (Step 0)
- [ ] Read ~/.claude/CLAUDE.md
- [ ] Count total lines
- [ ] List all ## sections with line counts
- [ ] Identify sections >20 lines

ステップ 2：各セクションを分類する

20 行を超える各セクションについて、次の点を判断します。

1. 頻度：この情報はどのくらいの頻度で必要になりますか？
2. 複雑さ：コードブロック、表、または詳細な手順が含まれていますか？
3. 再利用性：他のユーザーもこの情報をスキルとして活用できますか？

ステップ 3：変更を提案する

次の形式で最適化計画を提示します。

## Optimization Proposal

**Current**: X lines
**After**: Y lines (Z% reduction)

| Section | Lines | Action | Destination |
|---------|-------|--------|-------------|
| Section A | 50 | Move to references | ~/.claude/references/section_a.md |
| Section B | 80 | Extract to skill | skill-name/ |
| Section C | 5 | Keep | - |

ステップ 3.5：実行前の確認チェックリスト

重要：変更を実行する前に、情報が完全であることを確認してください。

移動または変更する各セクションについて、次の手順を実行します。

1. 確認する重要項目を抽出します。

   • 認証情報／パスワード／API キー
   • 重要なルール（「X を絶対にしない」「必ず Y をする」）
   • 具体的な値（ポート、IP、URL、パス）
   • 頻繁に参照されるコードスニペット
   • 他のセクションへの相互参照

2. 確認チェックリストを作成します。

   ## Verification Checklist for [Section Name]
   
   | Key Item | Original Location | New Location | Verified |
   |----------|-------------------|--------------|----------|
   | Server IP 47.96.x.x | Line 123 | infrastructure.md:15 | [ ] |
   | "Never push to main" rule | Line 45 | Kept in CLAUDE.md | [ ] |
   | Login credentials | Line 200 | api-login.md:30 | [ ] |
   

3. 相互参照を確認します。

   • セクション A がセクション B を参照している場合、移動後もリンクが機能することを確認します
   • 必要に応じて相対パスを絶対パスに変更します

ステップ 4：変更を適用する

ユーザーの承認を得て、確認チェックリストを完了した後、次の作業を行います。

1. ~/.claude/references/ に参照ファイルを作成します
2. 移動した内容への参照を CLAUDE.md に追加します
3. 該当する場合はスキルを作成します
4. チェックリストの各項目が新しい場所に存在することを確認します
5. 最終的な行数を報告します

ステップ 5：最適化後のテスト

Claude が移動した内容を引き続き見つけられることを確認します。

1. 見つけやすさをテストする：移動した内容が必要になる質問をします。

   Test queries to run:
   - "How do I connect to the production database?"
   - "What are the deployment steps for [service]?"
   - "Show me the credentials for [system]"
   

2. 参照リンクの機能を確認する：「See reference.md」というリンクがそれぞれ機能することを確認します。

   # Check all referenced files exist
   grep -oh '`~/.claude/references/[^`]*`' ~/.claude/CLAUDE.md | \
     sed 's/`//g' | while read f; do
       eval test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
     done
   

3. バックアップと比較する：意図しない削除がないことを確認します。

   diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" | head -20
   

4. 結果を記録する：

   ## Optimization Results
   
   | Metric | Before | After |
   |--------|--------|-------|
   | Total lines | X | Y |
   | Reduction | - | Z% |
   | References created | - | N files |
   | Skills extracted | - | M skills |
   
   **Verification**: All N checklist items verified ✓
   **Testing**: All K test queries returned correct information ✓
   

参照ファイルの形式

~/.claude/references/ に内容を移動する場合：

# [Section Title]

[Full original content, possibly enhanced with additional examples]

CLAUDE.md の参照形式

移動したセクションを次の内容に置き換えます。

## [Section Title]

[One-line summary]. See `~/.claude/references/[filename].md`

ベストプラクティス

• 中核となる原則を見える場所に保つ：「Xを決して行わない」といったルールは、CLAUDE.md に記載しておきます
• 関連するリファレンスをまとめる：関連性のある小さなセクションは、1つのリファレンスファイルにまとめます
• すぐに使えるコマンドを残す：よく使うコマンドのスニペットは、CLAUDE.md に残しておきます
• 最適化の後にテストする：移動した情報を Claude が引き続き見つけられることを確認します

よくあるパターン

パターン：インフラストラクチャ／認証情報

変更前：API の使用例、デプロイスクリプト、サーバー一覧をすべて記載 変更後：~/.claude/references/infrastructure.md への1行の参照を記載

パターン：コード生成ルール

変更前：例を含む、50行以上のコーディング規約 変更後：箇条書きのルールは残し、例はリファレンスに移動

パターン：再利用可能なワークフロー

変更前：完全なスクリプトを CLAUDE.md に埋め込む 変更後：scripts/ ディレクトリを含むスキルに切り出す

プロジェクトレベルとユーザーレベルの CLAUDE.md

このスキルはどちらの種類にも対応していますが、最適な方法は異なります。

ユーザーレベル（~/.claude/CLAUDE.md）

項目	方針
リファレンスの配置場所	~/.claude/references/
対象範囲	個人の設定、全体に適用するルール
共有	共有せず、個人のみで使用
目標サイズ	100～200行が理想

プロジェクトレベル（/path/to/project/CLAUDE.md）

項目	方針
リファレンスの配置場所	プロジェクトのルートにある docs/ または .claude/
対象範囲	プロジェクト固有のパターン、アーキテクチャ
共有	Git にコミットし、チームと共有
目標サイズ	300～600行でも問題ありません（プロジェクトのコンテキストがより多く必要です）

主な違い

1. リファレンスのパス：プロジェクトレベルでは相対パス（docs/best-practices/）を使います
2. Git に関する考慮事項：プロジェクトのリファレンスはコードとともにバージョン管理されます
3. チーム内の合意：プロジェクトの CLAUDE.md には、チームの合意内容を反映します
4. 更新頻度：コードの進化に伴い、プロジェクトレベルの変更はより頻繁になります

プロジェクトレベルの参照形式

## [Section Title]

[Summary]. See `docs/06-best-practices/[topic].md`

注：プロジェクトの CLAUDE.md では、人間のチームメンバーが見つけやすいように、隠しディレクトリよりも docs/ を推奨します。

同梱リファレンス

• references/progressive_disclosure_principles.md — プログレッシブ・ディスクロージャーの設計原則の詳細