claude-md-improver

CLAUDE.md 改善ツール

コードベース全体の CLAUDE.md ファイルを監査、評価、改善し、Claude Code がプロジェクトについて最適なコンテキストを得られるようにします。

このスキルは CLAUDE.md ファイルに書き込むことができます。 品質レポートを提示してユーザーの承認を得た後、対象を絞った改善を CLAUDE.md ファイルに反映します。

ワークフロー

フェーズ 1：検出

リポジトリ内のすべての CLAUDE.md ファイルを検索します。

find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

ファイルの種類と場所：

種類	場所	用途
プロジェクトルート	./CLAUDE.md	プロジェクトの主要なコンテキスト（Git にコミットされ、チームで共有）
ローカルの上書き設定	./.claude.local.md	個人用／ローカル設定（Git で無視され、共有されない）
グローバルのデフォルト設定	~/.claude/CLAUDE.md	すべてのプロジェクトに適用されるユーザー全体のデフォルト設定
パッケージ固有	./packages/*/CLAUDE.md	モノレポ内のモジュールレベルのコンテキスト
サブディレクトリ	ネストされた任意の場所	機能／ドメイン固有のコンテキスト

注： Claude は親ディレクトリにある CLAUDE.md ファイルを自動的に検出するため、モノレポのセットアップもそのまま機能します。

フェーズ 2：品質評価

各 CLAUDE.md ファイルを品質基準に照らして評価します。詳しい評価基準については、references/quality-criteria.md を参照してください。

簡易評価チェックリスト：

基準	重み	確認事項
コマンド／ワークフローの記載	高	ビルド／テスト／デプロイのコマンドが記載されていますか？
アーキテクチャの明確さ	高	Claude はコードベースの構造を理解できますか？
自明でないパターン	中	注意点や特有の挙動が記載されていますか？
簡潔さ	中	冗長な説明や自明な情報がありませんか？
最新性	高	現在のコードベースの状態が反映されていますか？
実行可能性	高	指示は曖昧ではなく、実行可能ですか？

品質スコア：

• A（90～100）：包括的で、最新かつ実行可能
• B（70～89）：十分に網羅されており、軽微な不足がある
• C（50～69）：基本情報はあるが、重要なセクションが不足している
• D（30～49）：情報が乏しい、または古い
• F（0～29）：存在しない、または大幅に古い

フェーズ 3：品質レポートの出力

更新を行う前に、必ず品質レポートを出力してください。

形式：

## CLAUDE.md Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment

#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

#### 2. ./packages/api/CLAUDE.md (Package-specific)
...

フェーズ 4：対象を絞った更新

品質レポートを出力した後、更新する前にユーザーに確認を求めます。

更新ガイドライン（重要）：

1. 対象を絞った追加のみを提案する - 本当に役立つ情報に焦点を当てます。

   • 分析中に見つかったコマンドやワークフロー
   • コード内で見つかった注意点や自明でないパターン
   • 明確でなかったパッケージ間の関係
   • 有効なテスト方法
   • 設定特有の挙動

2. 最小限にとどめる - 次の内容は避けます。

   • コードから自明なことの言い換え
   • すでに網羅されている一般的なベストプラクティス
   • 再発する可能性の低い一度限りの修正
   • 一文で足りる内容の冗長な説明

3. 差分を示す - 変更ごとに、次の内容を示します。

   • 更新する CLAUDE.md ファイル
   • 具体的な追加内容（差分または引用ブロック）
   • 今後のセッションで役立つ理由の簡潔な説明

差分の形式：

### Update: ./CLAUDE.md

**Why:** Build command was missing, causing confusion about how to run the project.

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # Start development server on port 3000
+ ```

### Phase 5: Apply Updates

After user approval, apply changes using the Edit tool. Preserve existing content structure.

## Templates

See [references/templates.md](references/templates.md) for CLAUDE.md templates by project type.

## Common Issues to Flag

1. **Stale commands**: Build commands that no longer work
2. **Missing dependencies**: Required tools not mentioned
3. **Outdated architecture**: File structure that's changed
4. **Missing environment setup**: Required env vars or config
5. **Broken test commands**: Test scripts that have changed
6. **Undocumented gotchas**: Non-obvious patterns not captured

## User Tips to Share

When presenting recommendations, remind users:

- **`#` key shortcut**: During a Claude session, press `#` to have Claude auto-incorporate learnings into CLAUDE.md
- **Keep it concise**: CLAUDE.md should be human-readable; dense is better than verbose
- **Actionable commands**: All documented commands should be copy-paste ready
- **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
- **Global defaults**: Put user-wide preferences in `~/.claude/CLAUDE.md`

## What Makes a Great CLAUDE.md

**Key principles:**
- Concise and human-readable
- Actionable commands that can be copy-pasted
- Project-specific patterns, not generic advice
- Non-obvious gotchas and warnings

**Recommended sections** (use only what's relevant):
- Commands (build, test, dev, lint)
- Architecture (directory structure)
- Key Files (entry points, config)
- Code Style (project conventions)
- Environment (required vars, setup)
- Testing (commands, patterns)
- Gotchas (quirks, common mistakes)
- Workflow (when to do what)

## Related Skills

- **dependency-upgrade**: Include dependency hardening policies and lockfile/security workflow guidance when improving repository CLAUDE.md files