CLAUDE.md Optimizer

プロジェクトから情報を収集し、全CLAUDE.mdを発見・分析・適正化する。

ワークフロー

1. 収集 → 2. 発見 → 3. 分析（既存+ギャップ） → 4. レポート → 5. 適正化（ユーザー確認後）

Step 1: プロジェクト情報の収集

プロジェクトを走査し、CLAUDE.mdに記述すべき情報を収集する。

詳細な収集手順は references/collection-guide.md を参照。

収集カテゴリと優先度

優先度	カテゴリ	収集源	CLAUDE.mdに書く理由
High	実行コマンド	package.json scripts, Makefile, CI設定	毎セッション必要。推測させると間違える
High	テスト方法	テストフレームワーク設定, CI	正しいテスト実行が品質の前提
High	安全制約・必須ルール	.gitignore, CI checks, linter設定	違反時の影響が大きい
Med	技術スタック概要	package.json, 設定ファイル群	コードベースの地図として有用
Med	アーキテクチャ・責務境界	ディレクトリ構造, README	設計意図はコードから読み取りにくい
Med	命名規約・コードスタイル	既存コードのパターン, linter設定	linterで強制できない規約のみ
Low	設計判断の背景（WHY）	ADR, README, git history	重要だが長くなりやすい。要約のみ
Low	ワークフロー	CONTRIBUTING.md, git history	ブランチ戦略等。存在すれば記載

収集の原則

• 書くべき: Claudeが毎回推測すべきでない情報（推測ミスのコストが高い）
• 書かない: コードや設定ファイルから一意に確定できる情報
• 境界: linter/formatter設定で強制されるルール → 書かない。強制されない慣習 → 書く

Step 2: 既存CLAUDE.mdの発見とモード判定

プロジェクト内の全CLAUDE.mdファイルを収集する。

find . -name "CLAUDE.md" -o -name "CLAUDE.local.md" | sort

併せて確認:

• ~/.claude/CLAUDE.md（グローバル設定）
• .claude/settings.json（Hooks定義）
• .claude/skills/（Skills定義）
• .claude/commands/（カスタムコマンド）

モード判定

状態	モード	Step 3の動作
ルートCLAUDE.mdが存在しない	新規作成	7観点分析をスキップ → 収集結果から新規生成
ルートCLAUDE.mdが存在する	適正化	7観点分析 + ギャップ分析を実行

いずれのモードでもサブディレクトリCLAUDE.md提案（Step 3C）は実行する。

Step 3: 分析

A. 既存CLAUDE.mdの7観点分析（適正化モードのみ）

新規作成モードではスキップ。既存CLAUDE.mdがある場合のみ実行する。

詳細な分析基準は references/best-practices.md を参照。

#	観点	確認内容
1	量の適正性	命令数が実質100-150件以下か
2	内容の適正性	コードから読み取れない＋毎セッション必要な情報のみか
3	NG内容の検出	書くべきでない内容が混入していないか
4	情報配置の適正性	CLAUDE.md / Skills / Hooks / commands の使い分けは正しいか
5	階層の適正性	グローバル / プロジェクト / サブディレクトリの使い分けは正しいか
6	強調の適正性	重要ルールの強調手法は適切か
7	構造の適正性	推奨テンプレートに沿っているか

B. ギャップ分析（収集情報 vs 既存CLAUDE.md）

適正化モード: Step 1の収集情報と既存CLAUDE.mdを突き合わせ、不足・過剰・矛盾を検出する。

ギャップ種別	検出方法	重大度
不足: 収集したが未記載	収集カテゴリのHigh項目が欠落	🔴（High）/ 🟡（Med/Low）
過剰: コードから読み取れるのに記載	設定ファイルと重複する記述	🟡
矛盾: 収集情報と既存記述が不一致	実際のコマンドと記載コマンドの差異等	🔴
陳腐化: 現在のコードに存在しない記述	参照先ファイル・コマンドの実在確認	🔴

新規作成モード: 収集した全情報を優先度順に整理し、テンプレートの各セクションにマッピングする。ギャップ分析は不要（全てが新規提案）。

C. サブディレクトリCLAUDE.md提案

以下のいずれかに該当するディレクトリにCLAUDE.md新設を提案する:

提案基準	具体例
ルートと技術スタック・ツールチェーンが異なる	モノレポ内の別パッケージ、フロント/バック分離
ルートと異なるローカルルールが存在する	独自の命名規則、テスト方法、デプロイ手順
誤適用時の影響が大きい領域	決済・認証・インフラ設定等のセキュリティ関連
ルートCLAUDE.mdの特定セクションが肥大化の原因	50行超のサブディレクトリ固有記述

提案しない場合:

• ルートの規約がそのまま適用されるディレクトリ
• ファイル数が少なく単純な構造のディレクトリ

Step 4: レポート出力

モードに応じたレポートを出力する。

新規作成モードのレポート

## CLAUDE.md 新規作成レポート

### 収集結果サマリー
- 検出した技術スタック: [言語, フレームワーク, ...]
- 主要コマンド: dev / test / build / lint
- サブディレクトリCLAUDE.md提案: N件

### 提案するCLAUDE.md
（テンプレートに収集結果を埋めた内容をプレビュー表示）

### サブディレクトリCLAUDE.md提案
1. `path/to/dir/CLAUDE.md` - 提案理由と記載すべき内容の要約

### ユーザーへの確認質問
（収集だけでは判断できなかった項目を質問）

適正化モードのレポート

## CLAUDE.md 適正化レポート

### 対象ファイル
- `./CLAUDE.md` (XX行, 推定命令数: NN件)
- `./src/feature/CLAUDE.md` (YY行, 推定命令数: MM件)

### 収集結果サマリー
- 検出した技術スタック: [言語, フレームワーク, ...]
- 主要コマンド: dev / test / build / lint
- サブディレクトリCLAUDE.md提案: N件

### 問題サマリー
- 🔴 要対応: X件（ギャップ・矛盾・NG内容）
- 🟡 推奨: Y件（不足補完・配置変更・構造改善）
- 🟢 良好: Z件

### 検出された問題

#### 🔴 要対応

1. **[観点/ギャップ種別] 問題タイトル**
   - 該当箇所: `ファイル:行` / 新規提案
   - 問題: 具体的な説明
   - 改善案: 具体的な改善方法
   - 根拠: 収集した情報源

#### 🟡 推奨
...

### サブディレクトリCLAUDE.md提案
1. `path/to/dir/CLAUDE.md` - 提案理由と記載すべき内容の要約

### 推奨アクション（優先順）
1. [最優先] 矛盾・陳腐化の修正
2. [高] 不足しているHigh情報の追加
3. [中] NG内容の削除/移動
4. [低] 構造改善・サブディレクトリ分離

Step 5: 適正化の実行

ユーザー確認後、モードに応じたアクションを実行する。

新規作成モード

• 生成: 収集結果を元にテンプレートを埋めてルートCLAUDE.mdを作成
• 新設: サブディレクトリCLAUDE.mdの作成（提案承認後）
• 補完: ユーザーの確認質問への回答を反映

適正化モード

• 追加: 収集した不足情報をCLAUDE.mdに追記
• 修正: 矛盾・陳腐化した記述を現状に合わせて更新
• 削除: コードから読み取れる情報、冗長な記述を削除
• 移動: 特定ドメイン知識→Skills、毎回実行処理→Hooks、ワークフロー→commands
• 新設: サブディレクトリCLAUDE.mdの作成（提案承認後）
• 書き換え: 曖昧な記述の明確化、禁止事項への代替手段追加、構造の整理
• 強調調整: 重要ルールにIMPORTANT:追加、冒頭・末尾への配置変更

IMPORTANT: いずれのモードでも、実行前に必ずユーザーに変更内容を提示し確認を得ること。

推定命令数の数え方

以下をそれぞれ1命令としてカウントする:

• 箇条書きの各項目
• テーブルの各行（ヘッダー除く）
• コードブロック内の各コマンド行
• 独立した文（段落内の各文）

セクション見出しや空行はカウントしない。バジェット: システムプロンプト約50件 + CLAUDE.md実質100-150件。

テンプレート（新規作成時）

CLAUDE.mdが存在しないプロジェクトでは、Step 1の収集結果を元に以下のテンプレートを埋めて提案する:

# [プロジェクト名]

## Overview
[サービスの目的を1-2文で]

## Tech Stack
- [フレームワーク/ライブラリ]
- [DB/インフラ]

## Commands
- dev:       [コマンド]
- test:      [コマンド]
- typecheck: [コマンド]
- build:     [コマンド]

## Code Style
- [linterで強制されない慣習のみ]
- [命名規則]

## Architecture
- [重要なディレクトリの役割と設計意図]
- [責務境界]

## Workflow
- [ブランチ戦略]
- [PR / マージ方針]

## Known Gotchas
- [プロジェクト固有の落とし穴と代替手段]