macOS Cleaner

Overview

macOS のディスク使用量をインテリジェントに分析し、ストレージ空き容量を回復するための実行可能なクリーンアップ推奨を提供します。本スキルは安全第一の哲学に従います：徹底的に分析し、明確な結果を提示し、削除を実行する前に明示的なユーザー確認が必須です。

対象ユーザー: ファイルシステムを理解する基本的な技術知識を持ち、macOS で何が削除しても安全かについてガイダンスが必要なユーザー。

Core Principles

1. 安全第一、決してバイパスしない: 明示的なユーザー確認なしに危険なコマンド (rm -rf、mo clean など) を実行しないこと。ショートカットや回避策は禁止。
2. 正確な削除のみ: 正確なオブジェクト ID/名前を指定して削除。バッチプルーンコマンドは使用しない。
3. すべてのオブジェクトをリストアップ: 報告書には「未使用イメージが 12 GB」ではなく、具体的なすべてのイメージ・ボリューム・コンテナを示す。
4. 見栄えより価値: クリーンアップの目標は削除容量を最大化することではなく、本当に不要なもの vs 価値あるキャッシュを識別すること。有用なキャッシュを 50GB も削除して大きな数字を見せるのは有害。
5. ネットワーク環境への配慮: 多くのユーザー（特に中国）は遅くて不安定なインターネット環境です。キャッシュの再ダウンロードに数時間かかることがあります。30 分のダウンロード時間を短縮できるキャッシュは保持する価値があります。
6. 影響分析が必須: すべてのクリーンアップ推奨に「削除した場合どうなるか」という列を含める。項目をただ列挙するだけでなく、結果を説明するか。
7. 削除前にダブルチェック: 削除前に各 Docker オブジェクトを独立した交差検証で確認（ステップ 2A 参照）。
8. 速度より忍耐強さ: ディスクスキャンは 5～10 分かかることがあります。遅い操作を中断したりスキップしない。ユーザーに定期的に進捗を報告する。
9. ユーザーがクリーンアップを実行: 分析後、ユーザーが自分で実行するクリーンアップコマンドを提供します。クリーンアップを自動実行しない。
10. 保守的なデフォルト: 迷ったときは削除しない。慎重さを優先する。

絶対的な禁止事項:

• ❌ docker image prune、docker volume prune、docker system prune またはいかなる prune ファミリーコマンドも使用しない（例外：docker builder prune は安全 — ビルドキャッシュには中間レイヤーのみが含まれ、ユーザーデータは含まれない）
• ❌ docker container prune は使用しない — 停止したコンテナはいつでも再開される可能性がある
• ❌ 明示的な確認なしにユーザーディレクトリで rm -rf を実行しない
• ❌ --dry-run プレビューなしに mo clean を実行しない
• ❌ 時間を短縮するために分析ステップをスキップしない
• ❌ Mole コマンドに --help を追加しない（mo --help のみが安全）
• ❌ カテゴリのみを含むクリーンアップレポートを提示しない — すべてのオブジェクトを個別にリストアップする
• ❌ クリーンアップ数を水増しするためだけに有用なキャッシュを削除することを推奨しない

Workflow Decision Tree

ユーザーがディスク容量の問題を報告
           ↓
    クイック診断
           ↓
    ┌──────┴──────┐
    │             │
 即座の       深い分析
クリーンアップ  （下に続く）
    │             │
    └──────┬──────┘
           ↓
  結果を提示
           ↓
 ユーザーが確認
           ↓
  クリーンアップ実行
           ↓
  結果を検証

Step 1: Mole によるクイック診断

主要ツール: ディスク分析に Mole を使用します。包括的でカテゴリ化された結果を提供します。

1.1 プリフライトチェック

# Mole のインストールとバージョンを確認
which mo && mo --version

# インストールされていない場合
brew install tw93/tap/mole

# 更新を確認（Mole は頻繁に更新される）
brew info tw93/tap/mole | head -5

# 古い場合はアップグレード
brew upgrade tw93/tap/mole

1.2 分析方法を選択

重要: 主要な分析ツールとして mo clean --dry-run ではなく mo analyze を使用してください。

コマンド	目的	使用する場合
mo analyze	インタラクティブなディスク使用量エクスプローラー（TUI ツリービュー）	主要: ストレージ消費量を理解する場合
mo clean --dry-run	クリーンアップカテゴリのプレビュー	二次: mo analyze の後、クリーンアップを見る場合のみ

mo analyze を推奨する理由:

• インタラクティブなツリーナビゲーション専用のディスク分析ツール
• 特定のディレクトリへのドリルダウンが可能
• クリーンアップカテゴリだけでなく、実際のディスク使用量の内訳を表示
• ストレージ消費量の理解に更に有用

1.3 tmux 経由での分析実行

重要: Mole は TTY が必要です。Claude Code から常に tmux を使用してください。

重要なタイミング注: ホームディレクトリのスキャンは遅い（大きなディレクトリの場合 5～10 分以上）。事前にユーザーに知らせ、忍耐強く待ってください。

# tmux セッション作成
tmux new-session -d -s mole -x 120 -y 40

# ディスク分析実行（主要ツール - インタラクティブ TUI）
tmux send-keys -t mole 'mo analyze' Enter

# スキャンを待つ - 忍耐強くいてください！
# ホームディレクトリのスキャンは通常 5～10 分かかります
# ユーザーに定期的に進捗を報告してください
sleep 60 && tmux capture-pane -t mole -p

# TUI を矢印キーで操作
tmux send-keys -t mole Down    # 次の項目に移動
tmux send-keys -t mole Enter   # アイテムを展開/選択
tmux send-keys -t mole 'q'     # 完了時に終了

代替案: クリーンアッププレビュー（mo analyze の後に使用）

# ドライラン（安全 - 削除なし）を実行
tmux send-keys -t mole 'mo clean --dry-run' Enter

# スキャンを待つ（30 秒ごとにユーザーに進捗を報告）
# 忍耐強くいてください！大きなディレクトリは 5～10 分かかります
sleep 30 && tmux capture-pane -t mole -p

1.4 進捗レポーティング

ユーザーに定期的にスキャン進捗を報告します：

📊 ディスク分析進行中...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️  経過: 2 分

現在の状態:
✅ Applications: 49.5 GB（完了）
✅ System Library: 10.3 GB（完了）
⏳ Home: スキャン中...（5～10 分かかる可能性があります）
⏳ App Library: 保留中

スキャンが完了するまで忍耐強く待機中です。
30 秒後に再度報告します...

1.5 最終結果を提示

スキャン完了後、構造化された結果を提示します：

📊 ディスク空き容量分析（Mole 経由）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
空き容量: 27 GB

🧹 回復可能な容量（ドライランプレビュー）:

➤ ユーザー必須
  • ユーザーアプリキャッシュ:     16.67 GB
  • ユーザーアプリログ:      102.3 MB
  • ゴミ箱:              642.9 MB

➤ ブラウザキャッシュ
  • Chrome キャッシュ:       1.90 GB
  • Safari キャッシュ:       4 KB

➤ 開発者向けツール
  • uv キャッシュ:           9.96 GB
  • npm キャッシュ:          （検出）
  • Docker キャッシュ:       （検出）
  • Homebrew キャッシュ:     （検出）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
回復可能な合計: ~30 GB

⚠️ これはドライランプレビューです。ファイルは削除されていません。

Step 2: 深い分析カテゴリ

以下のカテゴリを系統的にスキャンします。詳細は references/cleanup_targets.md を参照してください。

Category 1: システム・アプリケーションキャッシュ

分析対象の場所:

• ~/Library/Caches/* - ユーザーアプリケーションキャッシュ
• /Library/Caches/* - システム全体のキャッシュ（sudo 必要）
• ~/Library/Logs/* - アプリケーションログ
• /var/log/* - システムログ（sudo 必要）

分析スクリプト:

scripts/analyze_caches.py --user-only

安全レベル: 🟢 削除して安全（アプリが再生成する）

保持する例外:

• ブラウザが実行中のブラウザキャッシュ
• IDE キャッシュ（次回の起動が遅くなる可能性）
• パッケージマネージャーキャッシュ（Homebrew、pip、npm）

Category 2: アプリケーション残存物

分析対象の場所:

• ~/Library/Application Support/* - アプリデータ
• ~/Library/Preferences/* - 設定ファイル
• ~/Library/Containers/* - サンドボックス化されたアプリデータ

分析方法:

1. /Applications にインストール済みアプリケーションをリストアップ
2. ~/Library/Application Support と相互参照
3. 孤立したフォルダを識別（アプリ削除後のデータ残存）

分析スクリプト:

scripts/find_app_remnants.py

安全レベル: 🟡 注意が必要

• ✅ 安全: 明らかにアンインストール済みアプリのフォルダ
• ⚠️ 最初に確認: 稀に使用するアプリのフォルダ
• ❌ 保持: アクティブなアプリケーションデータ

Category 3: 大きなファイルと重複

分析スクリプト:

scripts/analyze_large_files.py --threshold 100MB --path ~

重複を検索（オプション、リソース集約的）:

# fdupes がインストール済みの場合
if command -v fdupes &> /dev/null; then
  fdupes -r ~/Documents ~/Downloads
fi

結果を提示:

📦 大きなファイル（>100MB）:
━━━━━━━━━━━━━━━━━━━━━━━━
1. movie.mp4                    4.2 GB  ~/Downloads
2. dataset.csv                  1.8 GB  ~/Documents/data
3. old_backup.zip               1.5 GB  ~/Desktop
...

🔁 重複ファイル:
- screenshot.png（3 コピー）     各 15 MB
- document_v1.docx（2 コピー）   各 8 MB

安全レベル: 🟡 ユーザーの判断が必要

Category 4: 開発環境のクリーンアップ

削除対象:

• Docker: イメージ、コンテナ、ボリューム、ビルドキャッシュ
• Homebrew: キャッシュ、旧バージョン
• Node.js: node_modules、npm キャッシュ
• Python: pip キャッシュ、__pycache__、venv
• Git: アーカイブプロジェクト内の .git フォルダ

分析スクリプト:

scripts/analyze_dev_env.py

結果例:

🐳 Docker リソース:
- 未使用イメージ:      12 GB
- 停止したコンテナ:  2 GB
- ビルドキャッシュ:         8 GB
- 孤立したボリューム:    3 GB
合計可能:      25 GB

📦 パッケージマネージャー:
- Homebrew キャッシュ:      5 GB
- npm キャッシュ:           3 GB
- pip キャッシュ:           1 GB
合計可能:       9 GB

🗂️  古いプロジェクト:
- archived-project-2022/.git  500 MB
- old-prototype/.git          300 MB

クリーンアップコマンド（確認が必要）:

# Homebrew クリーンアップ（安全）
brew cleanup -s

# npm _npx のみ（安全 - 一時パッケージ）
rm -rf ~/.npm/_npx

# pip キャッシュ（注意して使用）
pip cache purge

Docker クリーンアップ - 特別な処理が必須:

⚠️ これらのコマンドを使用しないこと:

# ❌ 危険 - 確認なしにすべてのボリュームを削除
docker volume prune -f
docker system prune -a --volumes

✅ 正しいアプローチ - ボリューム単位での確認:

# 1. すべてのボリュームをリストアップ
docker volume ls

# 2. どのプロジェクトが各ボリュームを持つか識別
docker volume inspect <volume_name>

# 3. ユーザーに各プロジェクトについて確認
# 例: 「'ragflow' プロジェクトのすべてのボリュームを削除しますか？」

# 4. 確認後に特定のボリュームのみ削除
docker volume rm ragflow_mysql_data ragflow_redis_data

安全レベル: 🟢 Homebrew/npm クリーンアップ、🔴 Docker ボリュームはプロジェクト単位での確認が必須

Step 2A: Docker 深い分析

包括的なカバレッジのために、エージェントチームで Docker リソースを並列分析します：

エージェント 1 — イメージ:

# すべてのイメージをサイズ順にリスト
docker images --format "table {{.ID}}\t{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}" | sort -k3 -h -r

# タグのないダングリングイメージを識別
docker images -f "dangling=true" --format "{{.ID}}\t{{.Size}}\t{{.CreatedSince}}"

# 各イメージについて、どのコンテナが参照しているかチェック
docker ps -a --filter "ancestor=<IMAGE_ID>" --format "{{.Names}}\t{{.Status}}"

エージェント 2 — コンテナとボリューム:

# ステータス付きすべてのコンテナ
docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Size}}"

# サイズ付きすべてのボリューム
docker system df -v | grep -A 1000 "VOLUME NAME"

# ダングリングボリュームを識別
docker volume ls -f dangling=true

# 各ボリュームについて、どのコンテナが使用しているかチェック
docker ps -a --filter "volume=<VOLUME_NAME>" --format "{{.Names}}"

エージェント 3 — システムレベル:

# Docker ディスク使用量サマリー
docker system df

# ビルドキャッシュ
docker builder du

# コンテナログサイズ
for c in $(docker ps -a --format "{{.Names}}"); do
  echo "$c: $(docker inspect --format='{{.LogPath}}' $c | xargs ls -lh 2>/dev/null | awk '{print $5}')"
done

バージョン管理への対応: バージョン管理されているイメージを識別（例：CLI で管理されている Supabase）。新しいバージョンが実行中であることが確認されたら、古いバージョンは削除しても安全です。Docker Compose の命名規則（ハイフン vs アンダースコア）に注意してください。

Step 2B: OrbStack 固有の分析

OrbStack ユーザーには追加の考慮事項があります。

data.img.raw はスパースファイル:

# 論理的なサイズ（8TB+ を表示できるが無意味）
ls -lh ~/Library/OrbStack/data/data.img.raw

# 実際のディスク使用量（これが重要）
du -h ~/Library/OrbStack/data/data.img.raw

論理的なサイズと実際のサイズの差は正常です。実際の使用量のみが重要です。

クリーンアップ後: ディスク容量の回復: OrbStack 内の Docker オブジェクトをクリーンアップした後、data.img.raw は自動的には縮小しません。ユーザーに指示：OrbStack の設定を開く → 「ディスク容量を回復」でスパースファイルをコンパクト化。

OrbStack ログ: 通常 1～2 MB の合計（~/Library/OrbStack/log/）。クリーンアップする価値なし。

Step 2C: ダブルチェック検証プロトコル

Docker オブジェクトを削除する前に、独立した検証を実行します。

イメージの場合:

# コンテナ（実行中または停止）がイメージを参照していないかチェック
docker ps -a --filter "ancestor=<IMAGE_ID>" --format "{{.Names}}\t{{.Status}}"

# 空の場合 → `docker rmi <IMAGE_ID>` で削除しても安全

ボリュームの場合:

# コンテナがボリュームをマウントしていないかチェック
docker ps -a --filter "volume=<VOLUME_NAME>" --format "{{.Names}}"

# 空の場合 → データベースボリュームかチェック（下記参照）
# データベースでなければ → `docker volume rm <VOLUME_NAME>` で削除しても安全

データベースボリューム警告ルール: ボリューム名に mysql、postgres、redis、mongo、mariadb が含まれている場合、必須でコンテンツを検査：

# 一時的なコンテナでデータベースボリュームコンテンツを検査
docker run --rm -v <VOLUME_NAME>:/data alpine ls -la /data
docker run --rm -v <VOLUME_NAME>:/data alpine du -sh /data/*

ユーザーがデータが不要であることを確認した後でのみ削除。

Step 3: Mole との統合

Mole (https://github.com/tw93/Mole) は macOS クリーンアップのための**コマンドラインインターフェース（CLI）**ツールです。キャッシュ、ログ、開発者向けツールなど、macOS のための包括的な分析とクリーンアップ機能を提供するインタラクティブなターミナルベースのツール。

重要な要件:

1. TTY 環境: Mole はインタラクティブコマンドに TTY が必要です。Claude Code またはスクリプトから実行する場合は tmux を使用してください。
2. バージョン確認: 使用する前に常に Mole が最新であることを確認してください。
3. 安全なヘルプコマンド: mo --help のみが安全です。他のコマンドに --help を追加しないでください。

インストール確認とアップグレード:

# インストール済みか確認してバージョン取得
which mo && mo --version

# インストールされていない場合
brew install tw93/tap/mole

# 更新を確認
brew info tw93/tap/mole | head -5

# 必要なら アップグレード
brew upgrade tw93/tap/mole

tmux で Mole を使用（Claude Code 必須）:

# TTY 環境用の tmux セッション作成
tmux new-session -d -s mole -x 120 -y 40

# 分析実行（安全、読み取り専用）
tmux send-keys -t mole 'mo analyze' Enter

# スキャンを待つ（大きなディレクトリの場合 5～10 分かかることがあります。忍耐強くいてください）
sleep 60

# 結果をキャプチャ
tmux capture-pane -t mole -p

# 完了時にクリーンアップ
tmux kill-session -t mole

利用可能なコマンド（mo --help から）:

コマンド	安全性	説明
mo --help	✅ 安全	すべてのコマンドを表示（安全なヘルプのみ）
mo analyze	✅ 安全	ディスク使用量エクスプローラー（読み取り専用）
mo status	✅ 安全	システムヘルスモニター
mo clean --dry-run	✅ 安全	クリーンアップをプレビュー（削除なし）
mo clean	⚠️ 危険	実際にファイルを削除
mo purge	⚠️ 危険	プロジェクトアーティファクトを削除
mo uninstall	⚠️ 危険	アプリケーションを削除

リファレンスガイド: 詳細な tmux ワークフローとトラブルシューティングについては references/mole_integration.md を参照してください。

Mole を使用した多層深掘り探索

重要: 包括的な分析のためには、トップレベルのスキャンだけでなく、多層探索を実行する必要があります。このセクションでは、Mole の TUI をナビゲートするための実証済みのワークフローを記載しています。

ナビゲーションコマンド

# セッション作成
tmux new-session -d -s mole -x 120 -y 40

# 分析開始
tmux send-keys -t mole 'mo analyze' Enter

# 初期スキャンを待つ
sleep 8 && tmux capture-pane -t mole -p

# ナビゲーションキー（tmux 経由で送信）
tmux send-keys -t mole Enter    # 選択したディレクトリに入る/展開
tmux send-keys -t mole Left     # 親ディレクトリに戻る
tmux send-keys -t mole Down     # 次の項目に移動
tmux send-keys -t mole Up       # 前の項目に移動
tmux send-keys -t mole 'q'      # TUI を終了

# 現在のビューをキャプチャ
tmux capture-pane -t mole -p

多層探索ワークフロー

ステップ 1: トップレベルの概要

# mo analyze を開始し、初期メニューを待つ
tmux send-keys -t mole 'mo analyze' Enter
sleep 8 && tmux capture-pane -t mole -p

# 出力例:
# 1. Home           289.4 GB (58.5%)
# 2. App Library    145.2 GB (29.4%)
# 3. Applications    49.5 GB (10.0%)
# 4. System Library  10.3 GB (2.1%)

ステップ 2: 最大のディレクトリに入る（Home）

tmux send-keys -t mole Enter
sleep 10 && tmux capture-pane -t mole -p

# 出力例:
# 1. Library       144.4 GB (49.9%)
# 2. Workspace      52.0 GB (18.0%)
# 3. .cache         19.3 GB (6.7%)
# 4. Applications   17.0 GB (5.9%)
# ...

ステップ 3: 特定のディレクトリにドリルダウン

# .cache に移動（3 番目の項目: Down Down Enter）
tmux send-keys -t mole Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 出力例:
# 1. uv           10.3 GB (55.6%)
# 2. modelscope    5.5 GB (29.5%)
# 3. huggingface   887.8 MB (4.7%)

ステップ 4: 戻って別のブランチを探索

# 親に戻る
tmux send-keys -t mole Left
sleep 2

# 別のディレクトリに移動
tmux send-keys -t mole Down Down Down Down Enter  # .npm に移動
sleep 5 && tmux capture-pane -t mole -p

ステップ 5: Library への深掘り

# Home に戻る、Library に移動
tmux send-keys -t mole Left
tmux send-keys -t mole Up Up Up Up Up Up Enter  # Library に移動
sleep 10 && tmux capture-pane -t mole -p

# 出力例:
# 1. Application Support  37.1 GB
# 2. Containers          35.4 GB
# 3. Developer           17.8 GB  ← Xcode はここ
# 4. Caches               8.2 GB

推奨される探索パス

包括的な分析のために、この探索ツリーに従ってください：

mo analyze
├── Home (Enter)
│   ├── Library (Enter)
│   │   ├── Developer (Enter) → Xcode/DerivedData、iOS DeviceSupport
│   │   ├── Caches (Enter) → Playwright、JetBrains など
│   │   └── Application Support (Enter) → アプリデータ
│   ├── .cache (Enter) → uv、modelscope、huggingface
│   ├── .npm (Enter) → _cacache、_npx
│   ├── Downloads (Enter) → 確認する大きなファイル
│   ├── .Trash (Enter) → ゴミ箱の内容を確認
│   └── miniconda3/その他 dev ツール (Enter) → 最後に使用した時期を確認
├── App Library → 通常は ~/Library と重複
└── Applications → インストール済みアプリ

時間の目安

ディレクトリ	スキャン時間	メモ
トップレベルメニュー	5～8 秒	高速
Home ディレクトリ	5～10 分	大きい、忍耐強くいてください
~/Library	3～5 分	多くの小さなファイル
サブディレクトリ	2～30 秒	サイズによって異なる

完全なセッション例

# 1. セッション作成
tmux new-session -d -s mole -x 120 -y 40

# 2. 分析開始して概要取得
tmux send-keys -t mole 'mo analyze' Enter
sleep 8 && tmux capture-pane -t mole -p

# 3. Home に入る
tmux send-keys -t mole Enter
sleep 10 && tmux capture-pane -t mole -p

# 4. .cache に入ると dev キャッシュが見える
tmux send-keys -t mole Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 5. Home に戻り、.npm に移動
tmux send-keys -t mole Left
sleep 2
tmux send-keys -t mole Down Down Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 6. Home に戻り、Library に移動
tmux send-keys -t mole Left
sleep 2
tmux send-keys -t mole Up Up Up Up Up Up Enter
sleep 10 && tmux capture-pane -t mole -p

# 7. Developer に入ると Xcode が見える
tmux send-keys -t mole Down Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 8. Xcode に入る
tmux send-keys -t mole Enter
sleep 5 && tmux capture-pane -t mole -p

# 9. DerivedData に入るとプロジェクトが見える
tmux send-keys -t mole Enter
sleep 5 && tmux capture-pane -t mole -p

# 10. クリーンアップ
tmux kill-session -t mole

探索による主な発見

多層探索後、以下のことが明らかになります：

1. DerivedData を使用しているプロジェクト - 特定のプロジェクト名
2. 実際に大きいキャッシュ - uv vs npm など
3. ファイルの年齢 - Mole は「>3mo」、「>7mo」、「>1yr」マーカーを表示
4. 特定のボリュームとその目的 - Docker プロジェクトデータ
5. クリーンアップできる Downloads - 古い dmg、重複ファイル

アンチパターン: 削除しないべきもの

重要: 以下のアイテムはクリーンアップ対象としてよく提案されていますが、ほとんどの場合、削除すべきではありません。消費する容量よりも提供する価値が大きいです。

保持すべきアイテム（アンチパターン）

アイテム	サイズ	削除しない理由	削除した場合の実際の影響
Xcode DerivedData	10+ GB	ビルドキャッシュは完全再構築で 10～30 分を節約	次のビルドに 10～30 分かかる
npm _cacache	5+ GB	ダウンロードされたパッケージがローカルキャッシュされている	npm install がすべてを再ダウンロード（中国では 30 分～2 時間）
~/.cache/uv	10+ GB	Python パッケージキャッシュ	すべての Python プロジェクトが PyPI から deps を再インストール
Playwright ブラウザ	3～4 GB	テスト自動化用ブラウザバイナリ	実行のたびに 2GB+ を再ダウンロード（30 分～1 時間）
iOS DeviceSupport	2～3 GB	デバイスデバッグに必須	デバイス接続時に Apple から再ダウンロード
Docker 停止したコンテナ	<500 MB	docker start でいつでも再開される可能性	コンテナ状態を失い、再作成が必要
~/.cache/huggingface	異なる	AI モデルキャッシュ	大きなモデルを再ダウンロード（数時間）
~/.cache/modelscope	異なる	AI モデルキャッシュ（中国）	同上
JetBrains キャッシュ	1+ GB	IDE のインデックスとキャッシュ	IDE が再インデックスに 5～10 分かかる

なぜこれが重要か

虚栄的な落とし穴: 「50GB をクリーンアップしました！」というのは気分がいいですが：

• ユーザーが次の 2 時間、npm パッケージを再ダウンロード
• 次の Xcode ビルドが 30 秒ではなく 30 分かかる
• AI プロジェクトが失敗（モデル再ダウンロード必要）

正しい考え方: 「50GB のキャッシュが見つかりました。実は、ほとんどが価値があり、保持すべきものです...」

実際に削除しても安全なもの

アイテム	安全な理由	影響
ゴミ箱	ユーザーが既に削除したファイル	なし - ユーザーの決定
Homebrew 旧バージョン	新しいバージョンに置き換え	稀：旧バージョンにロールバック不可
npm _npx	一時的な npx 実行	軽微：次の npx 再ダウンロード
孤立したアプリ残存物	アプリ既にアンインストール	なし - アプリが存在しない
特定の未使用 Docker ボリューム	プロジェクトが確認済みで放棄状態	なし - 真に放棄状態なら

レポート形式の要件

すべてのクリーンアップレポートはこのフォーマットに従い、影響分析を含める必要があります：

## ディスク分析レポート

### 分類凡例
| シンボル | 意味 |
|---------|------|
| 🟢 | **絶対に安全** - 負の影響なし、真に未使用 |
| 🟡 | **トレードオフが必要** - 有用なキャッシュ、削除にはコストがある |
| 🔴 | **削除しないこと** - 価値あるデータまたは積極的に使用中 |

### 発見事項

| アイテム | サイズ | 分類 | 説明 | 削除した場合の影響 |
|---------|--------|------|------|-------------------|
| ゴミ箱 | 643 MB | 🟢 | あなたが削除したファイル | なし |
| npm _npx | 2.1 GB | 🟢 | 一時的な npx パッケージ | 軽微な再ダウンロード |
| npm _cacache | 5 GB | 🟡 | パッケージキャッシュ | 30 分～2 時間の再ダウンロード |
| DerivedData | 10 GB | 🟡 | Xcode ビルドキャッシュ | 10～30 分のリビルド |
| Docker ボリューム | 11 GB | 🔴 | プロジェクトデータベース | **データ損失** |

### 推奨事項
🟢 マークのアイテムのみがクリーンアップ推奨です。
🟡 マークのアイテムは使用パターンに基づいてあなたが判断が必要です。
🔴 マークのアイテムは項目ごとに明示的な確認が必要です。

Docker レポート: オブジェクトレベルの詳細が必須

Docker レポートはカテゴリだけでなく、個別のオブジェクトをすべてリストアップする必要があります：

#### ダングリングイメージ（タグなし、コンテナ参照なし）
| イメージ ID | サイズ | 作成 | 安全？ |
|-----------|--------|------|-------|
| a02c40cc28df | 884 MB | 2 ヶ月前 | ✅ コンテナが使用していない |
| 555434521374 | 231 MB | 3 ヶ月前 | ✅ コンテナが使用していない |

#### 停止したコンテナ
| 名前 | イメージ | ステータス | サイズ |
|------|---------|----------|--------|
| ragflow-mysql | mysql:8.0 | 2 週間前に終了 | 1.2 GB |

#### ボリューム
| ボリューム | サイズ | マウント対象 | 内容 |
|----------|--------|-----------|------|
| ragflow_mysql_data | 1.8 GB | ragflow-mysql | MySQL データベース |
| redis_data | 500 MB | （なし - ダングリング） | Redis ダンプ |

#### 🔴 検査が必要なデータベースボリューム
| ボリューム | 検査内容 | ユーザーの決定 |
|----------|---------|-------------|
| ragflow_mysql_data | 8 つのデータベース、45 テーブル | 必要ですか？ |

高品質レポートテンプレート

多層探索後、このテンプレートを使用して結果を提示します：

## 📊 ディスク空き容量深掘り分析レポート

**分析日**: YYYY-MM-DD
**使用ツール**: Mole CLI + 多層ディレクトリ探索
**分析原則**: 安全第一、価値 > 虚栄

---

### 総覧

| 領域 | 合計使用量 | 主要な発見 |
|------|----------|----------|
| **Home** | XXX GB | Library が半分を占有（XXX GB） |
| **App Library** | XXX GB | Home/Library と統計重複 |
| **Applications** | XXX GB | アプリケーション本体 |

---

### 🟢 絶対に安全で削除可能（約 X.X GB）

| アイテム | サイズ | 場所 | 削除後の影響 | クリーンアップコマンド |
|---------|--------|------|-----------|-----------------|
| **ゴミ箱** | XXX MB | ~/.Trash | なし - あなたが削除を決定したファイル | ゴミ箱を空にする |
| **npm _npx** | X.X GB | ~/.npm/_npx | 次の npx コマンドで再ダウンロード | `rm -rf ~/.npm/_npx` |
| **Homebrew 旧バージョン** | XX MB | /opt/homebrew | なし - 新しいバージョンに置き換え済み | `brew cleanup --prune=0` |

**ゴミ箱の内容プレビュー**:
- [主要ファイルをリストアップ]

---

### 🟡 あなたの確認が必要なアイテム

#### 1. [プロジェクト名] (X.X GB) - [ステータス説明]

| サブディレクトリ | サイズ | 最後の使用 |
|------------|--------|----------|
| [サブディレクトリ 1] | X.X GB | >X 個月 |
| [サブディレクトリ 2] | X.X GB | >X 個月 |

**質問**: [ユーザーが答える必要がある質問]

---

#### 2. Downloads の古いファイル (X.X GB)

| ファイル/ディレクトリ | サイズ | 経過 | 推奨 |
|------------|--------|------|------|
| [ファイル 1] | X.X GB | - | [推奨] |
| [ファイル 2] | XXX MB | >X 個月 | [推奨] |

**推奨**: Downloads を手動で確認し、不要なファイルを削除してください。

---

#### 3. 停止中の Docker プロジェクト ボリューム

| プロジェクト接頭辞 | 想定されるデータ | あなたの確認 |
|-------------|-------------|---------|
| `project1_*` | MySQL、Redis | 使用中？ |
| `project2_*` | Postgres | 使用中？ |

**注釈**: `docker volume prune -f` は使用しません。あなたが確認後、特定プロジェクトのボリュームのみ削除します。

---

### 🔴 削除を推奨しないアイテム（価値あるキャッシュ）

| アイテム | サイズ | 保持理由 |
|---------|--------|--------|
| **Xcode DerivedData** | XX GB | [プロジェクト名]のコンパイルキャッシュ。削除後、次のビルドが X 分かかる |
| **npm _cacache** | X.X GB | ダウンロード済みすべての npm パッケージ。削除後、再ダウンロード必要 |
| **~/.cache/uv** | XX GB | Python パッケージキャッシュ。中国ネットワーク下での再ダウンロードは遅い |
| [その他の価値あるキャッシュ] | X.X GB | [保持理由] |

---

### 📋 その他の発見

| アイテム | サイズ | 説明 |
|---------|--------|------|
| **OrbStack/Docker** | XX GB | VM/コンテナの正常な占有 |
| [その他の発見] | X.X GB | [説明] |

---

### ✅ 推奨操作

**直ちに実行可能**（確認不要）:
```bash
# 1. ゴミ箱を空にする (XXX MB)
# 手動: Finder → ゴミ箱を空にする

# 2. npm _npx (X.X GB)
rm -rf ~/.npm/_npx

# 3. Homebrew 旧バージョン (XX MB)
brew cleanup --prune=0

予想回復量: ~X.X GB

---

あなたの確認後に実行:

1. [プロジェクト 1] - [確認が必要な質問]
2. [プロジェクト 2] - [確認が必要な質問]
3. Docker プロジェクト - もう使用しないプロジェクトを教えてください

### レポート品質チェックリスト

レポート提示前に以下を確認：

- [ ] すべてのアイテムに「削除した場合の影響」説明がある
- [ ] 🟢 アイテムが本当に安全（ゴミ箱、_npx、旧バージョン）
- [ ] 🟡 アイテムにユーザーの判断が必要（年齢情報、使用パターン）
- [ ] 🔴 アイテムが保持理由を説明
- [ ] Docker ボリュームがプロジェクト単位で、一括プルーンでない
- [ ] ネットワーク環境が考慮済み（中国 = 遅い再ダウンロード）
- [ ] 数字を水増しするだけのため有用なキャッシュ削除推奨がない
- [ ] 明確なアクションアイテムと正確なコマンドがある

## Step 4: 推奨を提示

結果をリスク レベル付きの実行可能な推奨に整形：

```markdown
# macOS クリーンアップ推奨事項

## サマリー
回復可能な合計容量: ~XX GB
現在の使用率: XX%

## 推奨アクション

### 🟢 実行しても安全（低リスク）
削除しても安全で、必要に応じて再生成されます：

1. **ゴミ箱を空にする** (~12 GB)
   - 場所: ~/.Trash
   - コマンド: `rm -rf ~/.Trash/*`

2. **システムキャッシュをクリア** (~45 GB)
   - 場所: ~/Library/Caches
   - コマンド: `rm -rf ~/Library/Caches/*`
   - メモ: アプリが次回起動時に少し遅くなる可能性

3. **Homebrew キャッシュ削除** (~5 GB)
   - コマンド: `brew cleanup -s`

### 🟡 確認推奨（中程度リスク）
削除前にこれらのアイテムを確認：

1. **大きなダウンロード** (~38 GB)
   - 場所: ~/Downloads
   - アクション: 不要なファイルを手動確認・削除
   - ファイル: [上位 10 ファイルをリスト]

2. **アプリケーション残存物** (~8 GB)
   - アプリ: [検出された未インストール済みアプリをリスト]
   - 場所: [パスをリスト]
   - アクション: アプリが真に未インストール済みか確認後削除

### 🔴 確実な場合のみ（高リスク）
本当に何をしているかわかる場合のみ削除：

1. **Docker ボリューム** (~3 GB)
   - 重要なデータが含まれるかもしれません
   - 確認: `docker volume ls`

2. **Time Machine ローカルスナップショット** (~XX GB)
   - 自動バックアップ。容量が必要になると削除されます
   - 確認コマンド: `tmutil listlocalsnapshots /`

Step 5: 確認付きで実行

重要: 明示的なユーザー確認なしに削除を実行しないこと。

インタラクティブ確認フロー:

# scripts/safe_delete.py の例
def confirm_delete(path: str, size: str, description: str) -> bool:
    """
    ユーザーに削除確認を求める。

    Args:
        path: ファイル/ディレクトリパス
        size: 人間が読める形式のサイズ
        description: 説明

    Returns:
        ユーザーが確認した場合は True、そうでなければ False
    """
    print(f"\n🗑️  削除を確認")
    print(f"━━━━━━━━━━━━━━━━━━")
    print(f"パス:        {path}")
    print(f"サイズ:      {size}")
    print(f"説明:       {description}")

    response = input("\nこのアイテムを削除しますか？ [y/N]: ").strip().lower()
    return response == 'y'

バッチ操作の場合:

def batch_confirm(items: list) -> list:
    """
    すべてのアイテムを表示し、バッチ確認を求める。

    削除をユーザーが承認したアイテムのリストを返す。
    """
    print("\n📋 削除するアイテム:")
    print("━━━━━━━━━━━━━━━━━━")
    for i, item in enumerate(items, 1):
        print(f"{i}. {item['path']} ({item['size']})")

    print("\nオプション:")
    print("  'all'    - すべてのアイテムを削除")
    print("  '1,3,5'  - 番号で特定のアイテムを削除")
    print("  'none'   - キャンセル")

    response = input("\nあなたの選択: ").strip().lower()

    if response == 'none':
        return []
    elif response == 'all':
        return items
    else:
        # 番号をパース
        indices = [int(x.strip()) - 1 for x in response.split(',')]
        return [items[i] for i in indices if 0 <= i < len(items)]

Step 6: 結果を検証

クリーンアップ後、結果を検証してレポート：

# クリーンアップ前後の比較
df -h /

# 回復した容量を計算
# (scripts/cleanup_report.py で処理)

レポート形式:

✅ クリーンアップ完了！

クリーンアップ前: 450 GB 使用中 (90%)
クリーンアップ後: 385 GB 使用中 (77%)
━━━━━━━━━━━━━━━━━━━━━━━━
回復: 65 GB

内訳:
- システムキャッシュ:        45 GB
- Downloads:            12 GB
- Homebrew キャッシュ:        5 GB
- アプリケーション残存物:  3 GB

⚠️ メモ:
- 初回起動時にアプリが遅くなる可能性があります
- 削除されたアイテムは Time Machine バックアップがなければ回復できません
- このクリーンアップを月 1 回の実行をお勧めします

💡 メンテナンスのヒント:
- Homebrew 自動クリーンアップを週 1 回設定: `brew cleanup`
- Downloads フォルダを月 1 回確認
- Finder の設定で「ゴミ箱を自動的に空にする」を有効化

ボーナス: Dockerfile 最適化の発見

イメージ分析中、過度に大きなイメージを発見したら、マルチステージビルド最適化を提案：

# 前: 884 MB（最終イメージ内に完全なビルド環境）
FROM node:20
COPY . .
RUN npm ci && npm run build
CMD ["node", "dist/index.js"]

# 後: ~150 MB（最終イメージにはランタイムのみ）
FROM node:20 AS builder
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

重要な技術: マルチステージビルド、slim/alpine ベースイメージ、.dockerignore、レイヤー順序。

⚠️ 安全ガイドライン

常に保持すべきもの

明示的なユーザー指示がない限り、以下を削除しないこと：

• ~/Documents、~/Desktop、~/Pictures の内容
• アクティブなプロジェクトディレクトリ
• データベースファイル（.db、.sqlite）
• アクティブなアプリの設定ファイル
• SSH キー、認証情報、証明書
• Time Machine バックアップ

⚠️ Sudo 確認が必要

これらの操作は管理者権限が必要です。ユーザーに手動実行を求める：

• /Library/Caches クリア（システム全体）
• /var/log クリア（システムログ）
• /private/var/folders クリア（システム一時ファイル）

プロンプト例:

⚠️ この操作には管理者権限が必要です。

以下のコマンドを手動で実行してください：
  sudo rm -rf /Library/Caches/*

⚠️ パスワードを入力するよう促されます。

💡 バックアップ推奨

10GB をクリーンアップする前に、以下を推奨：

💡 安全のヒント:
XX GB をクリーンアップする前に、Time Machine バックアップの作成をお勧めします。

クイックバックアップ確認:
  tmutil latestbackup

最近のバックアップがない場合、実行:
  tmutil startbackup

トラブルシューティング

「Operation not permitted」エラー

macOS は SIP（System Integrity Protection）により特定のシステムファイルの削除をブロック。

解決: 無理に強制しないこと。これらの保護はセキュリティのためにあります。

クリーンアップ後のアプリクラッシュ

稀ですが可能性があります。解決: アプリを再起動すると、必要なキャッシュが再生成されます。

Docker クリーンアップで重要なデータが削除

防止: クリーンアップ前に常に Docker ボリュームをリスト：

docker volume ls
docker volume inspect <volume_name>

リソース

scripts/

• analyze_caches.py - キャッシュディレクトリをスキャンして分類
• find_app_remnants.py - 孤立したアプリケーションデータを検出
• analyze_large_files.py - スマートフィルタリング付きで大きなファイルを検索
• analyze_dev_env.py - 開発環