macos-cleaner

macOS クリーナー

概要

macOS のディスク使用状況をインテリジェントに分析し、ストレージ容量を回復するための実行可能なクリーンアップの推奨事項を提示します。このスキルは安全性を最優先する方針に従います。徹底的に分析し、明確な調査結果を提示したうえで、削除を実行する前にユーザーから明示的な確認を得ます。

対象ユーザー：ファイルシステムの基本的な知識はあるものの、macOS で安全に削除できるものについて案内が必要なユーザーです。

基本原則

1. 安全性を最優先し、決して迂回しない：明示的なユーザー確認なしに、危険なコマンド（rm -rf、mo clean など）を決して実行しないでください。近道や回避策も使わないでください。
2. 見栄えより価値を重視：目標は、クリーンアップした容量を最大化することではありません。本当に不要なものと価値のあるキャッシュを見極めることです。大きな数値を見せるためだけに、役立つキャッシュを 50GB 削除するのは有害です。
3. ネットワーク環境への配慮：多くのユーザー（特に中国のユーザー）は、インターネットが低速または不安定です。キャッシュを再ダウンロードするには何時間もかかることがあります。ダウンロード時間を 30 分節約できるキャッシュは、残しておく価値があります。
4. 影響分析が必須：クリーンアップの推奨事項にはすべて、「削除するとどうなるか」の列を必ず含めてください。影響を説明せずに項目だけを列挙してはいけません。
5. 速度より忍耐を優先：ディスクスキャンには 5〜10 分かかることがあります。時間のかかる処理を決して中断したり、省略したりしないでください。定期的に進捗をユーザーに報告してください。
6. クリーンアップはユーザーが実行：分析後、ユーザー自身が実行するクリーンアップコマンドを提示してください。クリーンアップを自動実行してはいけません。
7. 保守的なデフォルト設定：迷った場合は削除しないでください。慎重な判断を優先してください。

絶対禁止事項：

• ❌ ユーザーディレクトリに対して rm -rf を自動実行してはいけません
• ❌ ドライランのプレビューを先に実行せずに mo clean を実行してはいけません
• ❌ docker volume prune -f または docker system prune -a --volumes を使ってはいけません
• ❌ 時間を節約するために分析手順を省略してはいけません
• ❌ Mole コマンドに --help を追加してはいけません（mo --help を除く）
• ❌ クリーンアップ量を水増しするためだけに、役立つキャッシュの削除を推奨してはいけません

ワークフローの判断ツリー

User reports disk space issues
           ↓
    Quick Diagnosis
           ↓
    ┌──────┴──────┐
    │             │
Immediate    Deep Analysis
 Cleanup      (continue below)
    │             │
    └──────┬──────┘
           ↓
  Present Findings
           ↓
   User Confirms
           ↓
   Execute Cleanup
           ↓
  Verify Results

ステップ 1：Mole による簡易診断

主なツール：ディスク分析には Mole を使用してください。包括的で、カテゴリ別に整理された結果が得られます。

1.1 事前チェック

# Check Mole installation and version
which mo && mo --version

# If not installed
brew install tw93/tap/mole

# Check for updates (Mole updates frequently)
brew info tw93/tap/mole | head -5

# Upgrade if outdated
brew upgrade tw93/tap/mole

1.2 分析方法を選択

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

コマンド	目的	使用する場面
mo analyze	インタラクティブなディスク使用状況エクスプローラー（TUI のツリービュー）	主用途：容量を消費しているものを把握する
mo clean --dry-run	クリーンアップ対象カテゴリのプレビュー	補助用途：クリーンアップのプレビューを確認する場合に限り、mo analyze の後で使用する

mo analyze を優先する理由：

• インタラクティブなツリーナビゲーションを備えた、専用のディスク分析ツールです
• 特定のディレクトリを掘り下げて調べられます
• クリーンアップ対象のカテゴリだけでなく、実際のディスク使用状況の内訳を表示します
• ストレージ消費の状況を把握するのに、より多くの情報が得られます

1.3 tmux 経由で分析を実行

重要：Mole の実行には TTY が必要です。Claude Code からは必ず tmux を使用してください。

重要なタイミングに関する注意：ホームディレクトリのスキャンには時間がかかります（大きなディレクトリでは 5〜10 分、またはそれ以上）。事前に所要時間をユーザーに伝え、辛抱強く待ってください。

# Create tmux session
tmux new-session -d -s mole -x 120 -y 40

# Run disk analysis (PRIMARY tool - interactive TUI)
tmux send-keys -t mole 'mo analyze' Enter

# Wait for scan - BE PATIENT!
# Home directory scanning typically takes 5-10 minutes
# Report progress to user regularly
sleep 60 && tmux capture-pane -t mole -p

# Navigate the TUI with arrow keys
tmux send-keys -t mole Down    # Move to next item
tmux send-keys -t mole Enter   # Expand/select item
tmux send-keys -t mole 'q'     # Quit when done

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

# Run dry-run preview (SAFE - no deletion)
tmux send-keys -t mole 'mo clean --dry-run' Enter

# Wait for scan (report progress to user every 30 seconds)
# Be patient! Large directories take 5-10 minutes
sleep 30 && tmux capture-pane -t mole -p

1.4 進捗の報告

スキャンの進捗を定期的にユーザーに報告してください。

📊 Disk Analysis in Progress...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️ Elapsed: 2 minutes

Current status:
✅ Applications: 49.5 GB (complete)
✅ System Library: 10.3 GB (complete)
⏳ Home: scanning... (this may take 5-10 minutes)
⏳ App Library: pending

I'm waiting patiently for the scan to complete.
Will report again in 30 seconds...

1.5 最終的な調査結果を提示

スキャン完了後、結果を構造化して提示してください。

📊 Disk Space Analysis (via Mole)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Free space: 27 GB

🧹 Recoverable Space (dry-run preview):

➤ User Essentials
  • User app cache:     16.67 GB
  • User app logs:      102.3 MB
  • Trash:              642.9 MB

➤ Browser Caches
  • Chrome cache:       1.90 GB
  • Safari cache:       4 KB

➤ Developer Tools
  • uv cache:           9.96 GB
  • npm cache:          (detected)
  • Docker cache:       (detected)
  • Homebrew cache:     (detected)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total recoverable: ~30 GB

⚠️ This was a dry-run preview. No files were deleted.

ステップ 2：カテゴリ別の詳細分析

次のカテゴリを体系的にスキャンしてください。詳しい説明は references/cleanup_targets.md を参照してください。

カテゴリ 1：システムとアプリケーションのキャッシュ

分析対象の場所：

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

分析スクリプト：

scripts/analyze_caches.py --user-only

安全レベル：🟢 通常は安全に削除できます（アプリがキャッシュを再生成します）

保持する例外：

• ブラウザーの実行中は、ブラウザーのキャッシュを保持します
• IDE のキャッシュ（次回の起動が遅くなる場合があります）
• パッケージマネージャーのキャッシュ（Homebrew、pip、npm）

カテゴリ 2：アプリケーションの残存データ

分析対象の場所：

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

分析方法：

1. /Applications にインストールされているアプリケーションを一覧表示します
2. ~/Library/Application Support と照合します
3. 孤立したフォルダー（アプリはアンインストール済みだが、データが残っているもの）を特定します

分析スクリプト：

scripts/find_app_remnants.py

安全レベル：🟡 注意が必要です

• ✅ 安全：明らかにアンインストール済みのアプリのフォルダー
• ⚠️ まず確認：使用頻度の低いアプリのフォルダー
• ❌ 保持：現在使用中のアプリケーションのデータ

カテゴリ 3：大容量ファイルと重複ファイル

分析スクリプト：

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

重複ファイルを検索（任意、リソースを大量に消費します）：

# Use fdupes if installed
if command -v fdupes &> /dev/null; then
  fdupes -r ~/Documents ~/Downloads
fi

調査結果を提示：

📦 Large Files (>100MB):
━━━━━━━━━━━━━━━━━━━━━━━━
1. movie.mp4                    4.2 GB  ~/Downloads
2. dataset.csv                  1.8 GB  ~/Documents/data
3. old_backup.zip               1.5 GB  ~/Desktop
...

🔁 Duplicate Files:
- screenshot.png (3 copies)     15 MB each
- document_v1.docx (2 copies)   8 MB each

安全レベル：🟡 ユーザーによる判断が必要です

カテゴリ 4：開発環境のクリーンアップ

対象：

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

分析スクリプト：

scripts/analyze_dev_env.py

調査結果の例：

🐳 Docker Resources:
- Unused images:      12 GB
- Stopped containers:  2 GB
- Build cache:         8 GB
- Orphaned volumes:    3 GB
Total potential:      25 GB

📦 Package Managers:
- Homebrew cache:      5 GB
- npm cache:           3 GB
- pip cache:           1 GB
Total potential:       9 GB

🗂️  Old Projects:
- archived-project-2022/.git  500 MB
- old-prototype/.git          300 MB

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

# Homebrew cleanup (safe)
brew cleanup -s

# npm _npx only (safe - temporary packages)
rm -rf ~/.npm/_npx

# pip cache (use with caution)
pip cache purge

Docker のクリーンアップ - 特別な対応が必要です：

⚠️ 次のコマンドは絶対に使用しないでください：

# ❌ DANGEROUS - deletes ALL volumes without confirmation
docker volume prune -f
docker system prune -a --volumes

✅ 正しい方法 - ボリュームごとに確認：

# 1. List all volumes
docker volume ls

# 2. Identify which projects each volume belongs to
docker volume inspect <volume_name>

# 3. Ask user to confirm EACH project they want to delete
# Example: "Do you want to delete all volumes for 'ragflow' project?"

# 4. Delete specific volumes only after confirmation
docker volume rm ragflow_mysql_data ragflow_redis_data

安全レベル：🟢 Homebrew/npm のクリーンアップ、🔴 Docker ボリュームはプロジェクトごとの確認が必要です

ステップ 3：Mole との統合

Mole (https://github.com/tw93/Mole) は、macOS を包括的にクリーンアップするための**コマンドラインインターフェイス（CLI）**ツールです。キャッシュ、ログ、開発者ツールなどを、対話型のターミナルベースで分析・クリーンアップできます。

重要な要件：

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

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

# Check if installed and get version
which mo && mo --version

# If not installed
brew install tw93/tap/mole

# Check for updates
brew info tw93/tap/mole | head -5

# Upgrade if needed
brew upgrade tw93/tap/mole

tmux で Mole を使用する（Claude Code では必須）：

# Create tmux session for TTY environment
tmux new-session -d -s mole -x 120 -y 40

# Run analysis (safe, read-only)
tmux send-keys -t mole 'mo analyze' Enter

# Wait for scan (be patient - can take 5-10 minutes for large directories)
sleep 60

# Capture results
tmux capture-pane -t mole -p

# Cleanup when done
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 を操作するための実証済みのワークフローについて説明します。

ナビゲーションコマンド

# Create session
tmux new-session -d -s mole -x 120 -y 40

# Start analysis
tmux send-keys -t mole 'mo analyze' Enter

# Wait for initial scan
sleep 8 && tmux capture-pane -t mole -p

# Navigation keys (send via tmux)
tmux send-keys -t mole Enter    # Enter/expand selected directory
tmux send-keys -t mole Left     # Go back to parent directory
tmux send-keys -t mole Down     # Move to next item
tmux send-keys -t mole Up       # Move to previous item
tmux send-keys -t mole 'q'      # Quit TUI

# Capture current view
tmux capture-pane -t mole -p

多層的な調査ワークフロー

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

# Start mo analyze, wait for initial menu
tmux send-keys -t mole 'mo analyze' Enter
sleep 8 && tmux capture-pane -t mole -p

# Example output:
# 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

# Example output:
# 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：特定のディレクトリをさらに調査する

# Go to .cache (3rd item: Down Down Enter)
tmux send-keys -t mole Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

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

ステップ 4：戻って別の分岐を調査する

# Go back to parent
tmux send-keys -t mole Left
sleep 2

# Navigate to different directory
tmux send-keys -t mole Down Down Down Down Enter  # Go to .npm
sleep 5 && tmux capture-pane -t mole -p

ステップ 5：Library を詳しく調査する

# Back to Home, then into Library
tmux send-keys -t mole Left
tmux send-keys -t mole Up Up Up Up Up Up Enter  # Go to Library
sleep 10 && tmux capture-pane -t mole -p

# Example output:
# 1. Application Support  37.1 GB
# 2. Containers          35.4 GB
# 3. Developer           17.8 GB  ← Xcode is here
# 4. Caches               8.2 GB

推奨される調査経路

包括的に分析するには、次の調査ツリーに従ってください。

mo analyze
├── Home (Enter)
│   ├── Library (Enter)
│   │   ├── Developer (Enter) → Xcode/DerivedData, iOS DeviceSupport
│   │   ├── Caches (Enter) → Playwright, JetBrains, etc.
│   │   └── Application Support (Enter) → App data
│   ├── .cache (Enter) → uv, modelscope, huggingface
│   ├── .npm (Enter) → _cacache, _npx
│   ├── Downloads (Enter) → Large files to review
│   ├── .Trash (Enter) → Confirm trash contents
│   └── miniconda3/other dev tools (Enter) → Check last used time
├── App Library → Usually overlaps with ~/Library
└── Applications → Installed apps

所要時間の目安

ディレクトリ	スキャン時間	備考
トップレベルメニュー	5～8 秒	高速
ホームディレクトリ	5～10 分	大容量のため、しばらくお待ちください
~/Library	3～5 分	小さなファイルが多数あります
サブディレクトリ	2～30 秒	サイズによって異なります

セッション全体の例

# 1. Create session
tmux new-session -d -s mole -x 120 -y 40

# 2. Start analysis and get overview
tmux send-keys -t mole 'mo analyze' Enter
sleep 8 && tmux capture-pane -t mole -p

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

# 4. Enter .cache to see dev caches
tmux send-keys -t mole Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 5. Back to Home, then to .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. Back to Home, enter 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. Enter Developer to see Xcode
tmux send-keys -t mole Down Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

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

# 9. Enter DerivedData to see projects
tmux send-keys -t mole Enter
sleep 5 && tmux capture-pane -t mole -p

# 10. Cleanup
tmux kill-session -t mole

調査で得られる主な知見

複数の階層を調査すると、次のことが分かります。

1. DerivedData を使用しているプロジェクト - 具体的なプロジェクト名
2. 実際に容量の大きいキャッシュ - uv、npm など
3. ファイルの経過期間 - Mole には「>3mo」、「>7mo」、「>1yr」のマーカーが表示されます
4. 各ボリュームとその用途 - Docker のプロジェクトデータ
5. 削除できるダウンロードファイル - 古い dmg、重複ファイル

アンチパターン：削除してはいけないもの

重要：以下の項目は、クリーンアップ対象として提案されることがよくありますが、消費する容量よりも得られるメリットのほうが大きいため、ほとんどの場合は削除しないでください。

KEEP（削除しない項目）

項目	サイズ	削除してはいけない理由	削除した場合の実際の影響
Xcode DerivedData	10+ GB	ビルドキャッシュにより、フルリビルドの時間を10～30分短縮できます	次回のビルドに10～30分余計にかかります
npm _cacache	5+ GB	ダウンロードしたパッケージをローカルにキャッシュします	npm install ですべてを再ダウンロードします（中国では30分～2時間）
~/.cache/uv	10+ GB	Python パッケージのキャッシュ	Python プロジェクトを実行するたびに、依存関係を PyPI から再インストールします
Playwright browsers	3-4 GB	自動テスト用のブラウザーバイナリ	毎回 2GB 以上を再ダウンロードします（30分～1時間）
iOS DeviceSupport	2-3 GB	デバイスのデバッグに必要です	デバイスを接続したときに Apple から再ダウンロードします
Docker stopped containers	<500 MB	docker start でいつでも再起動できます	コンテナーの状態が失われ、再作成が必要になります
~/.cache/huggingface	変動	AI モデルのキャッシュ	大容量のモデルを再ダウンロードします（数時間）
~/.cache/modelscope	変動	AI モデルのキャッシュ（中国）	上記と同じです
JetBrains caches	1+ GB	IDE のインデックスとキャッシュ	IDE のインデックス再作成に5～10分かかります

重要な理由

見栄えの罠：「50GB をクリーンアップしました！」と表示されると気分はよいですが、次のようなことが起こります。

• ユーザーはその後2時間かけて npm パッケージを再ダウンロードします
• 次回の Xcode ビルドに30秒ではなく30分かかります
• モデルの再ダウンロードが必要になり、AI プロジェクトが動作しなくなります

適切な考え方：「50GB 分のキャッシュを見つけました。そのほとんどが実際には役に立つため、残しておくべき理由を説明します……」

実際に安全に削除できるもの

項目	安全な理由	影響
ゴミ箱	ユーザーがすでにこれらのファイルを削除しています	なし - ユーザーが判断済みです
Homebrew old versions	新しいバージョンに置き換えられています	まれに、古いバージョンに戻せなくなることがあります
npm _npx	一時的な npx の実行ファイル	軽微：次回の使用時に npx が再ダウンロードします
削除済みアプリの残存ファイル	アプリはすでにアンインストールされています	なし - アプリは存在しません
未使用と確認された Docker volumes	プロジェクトが放棄されたことを確認済みです	なし - 本当に放棄されている場合

レポート形式の要件

すべてのクリーンアップレポートでは、影響分析を含む次の形式を必ず使用してください。

## Disk Analysis Report

### Classification Legend
| Symbol | Meaning |
|--------|---------|
| 🟢 | **Absolutely Safe** - No negative impact, truly unused |
| 🟡 | **Trade-off Required** - Useful cache, deletion has cost |
| 🔴 | **Do Not Delete** - Contains valuable data or actively used |

### Findings

| Item | Size | Classification | What It Is | Impact If Deleted |
|------|------|----------------|------------|-------------------|
| Trash | 643 MB | 🟢 | Files you deleted | None |
| npm _npx | 2.1 GB | 🟢 | Temp npx packages | Minor redownload |
| npm _cacache | 5 GB | 🟡 | Package cache | 30min-2hr redownload |
| DerivedData | 10 GB | 🟡 | Xcode build cache | 10-30min rebuild |
| Docker volumes | 11 GB | 🔴 | Project databases | **DATA LOSS** |

### Recommendation
Only items marked 🟢 are recommended for cleanup.
Items marked 🟡 require your judgment based on usage patterns.
Items marked 🔴 require explicit confirmation per-item.

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

複数の階層を調査した後、実績のある次のテンプレートを使って調査結果を提示します。

## 📊 磁盘空间深度分析报告

**分析日期**: 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 项目 Volumes

| 项目前缀 | 可能包含的数据 | 需要你确认 |
|---------|--------------|-----------|
| `project1_*` | MySQL, Redis | 还在用吗？ |
| `project2_*` | Postgres | 还在用吗？ |

**注意**: 我不会使用 `docker volume prune -f`，只会在你确认后删除特定项目的 volumes。

---

### 🔴 不建议删除的项目 (有价值的缓存)

| 项目 | 大小 | 为什么要保留 |
|------|------|-------------|
| **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 プロジェクト - 使用しないことが確定したプロジェクトを教えてください

### Report Quality Checklist

Before presenting the report, verify:

- [ ] Every item has "Impact If Deleted" explanation
- [ ] 🟢 items are truly safe (Trash, _npx, old versions)
- [ ] 🟡 items require user decision (age info, usage patterns)
- [ ] 🔴 items explain WHY they should be kept
- [ ] Docker volumes listed by project, not blanket prune
- [ ] Network environment considered (China = slow redownload)
- [ ] No recommendations to delete useful caches just to inflate numbers
- [ ] Clear action items with exact commands

## Step 4: Present Recommendations

Format findings into actionable recommendations with risk levels:

```markdown
# macOS Cleanup Recommendations

## Summary
Total space recoverable: ~XX GB
Current usage: XX%

## Recommended Actions

### 🟢 Safe to Execute (Low Risk)
These are safe to delete and will be regenerated as needed:

1. **Empty Trash** (~12 GB)
   - Location: ~/.Trash
   - Command: `rm -rf ~/.Trash/*`

2. **Clear System Caches** (~45 GB)
   - Location: ~/Library/Caches
   - Command: `rm -rf ~/Library/Caches/*`
   - Note: Apps may be slightly slower on next launch

3. **Remove Homebrew Cache** (~5 GB)
   - Command: `brew cleanup -s`

### 🟡 Review Recommended (Medium Risk)
Review these items before deletion:

1. **Large Downloads** (~38 GB)
   - Location: ~/Downloads
   - Action: Manually review and delete unneeded files
   - Files: [list top 10 largest files]

2. **Application Remnants** (~8 GB)
   - Apps: [list detected uninstalled apps]
   - Locations: [list paths]
   - Action: Confirm apps are truly uninstalled before deleting data

### 🔴 Keep Unless Certain (High Risk)
Only delete if you know what you're doing:

1. **Docker Volumes** (~3 GB)
   - May contain important data
   - Review with: `docker volume ls`

2. **Time Machine Local Snapshots** (~XX GB)
   - Automatic backups, will be deleted when space needed
   - Command to check: `tmutil listlocalsnapshots /`

ステップ 5：確認後に実行する

重要：ユーザーの明示的な確認なしに、削除を実行してはいけません。

対話形式での確認フロー：

# Example from scripts/safe_delete.py
def confirm_delete(path: str, size: str, description: str) -> bool:
    """
    Ask user to confirm deletion.

    Args:
        path: File/directory path
        size: Human-readable size
        description: What this file/directory is

    Returns:
        True if user confirms, False otherwise
    """
    print(f"\n🗑️  Confirm Deletion")
    print(f"━━━━━━━━━━━━━━━━━━")
    print(f"Path:        {path}")
    print(f"Size:        {size}")
    print(f"Description: {description}")

    response = input("\nDelete this item? [y/N]: ").strip().lower()
    return response == 'y'

一括操作の場合：

def batch_confirm(items: list) -> list:
    """
    Show all items, ask for batch confirmation.

    Returns list of items user approved.
    """
    print("\n📋 Items to Delete:")
    print("━━━━━━━━━━━━━━━━━━")
    for i, item in enumerate(items, 1):
        print(f"{i}. {item['path']} ({item['size']})")

    print("\nOptions:")
    print("  'all'    - Delete all items")
    print("  '1,3,5'  - Delete specific items by number")
    print("  'none'   - Cancel")

    response = input("\nYour choice: ").strip().lower()

    if response == 'none':
        return []
    elif response == 'all':
        return items
    else:
        # Parse numbers
        indices = [int(x.strip()) - 1 for x in response.split(',')]
        return [items[i] for i in indices if 0 <= i < len(items)]

ステップ 6：結果を確認する

クリーンアップ後に結果を確認し、ユーザーに報告します。

# Compare before/after
df -h /

# Calculate space recovered
# (handled by scripts/cleanup_report.py)

レポート形式：

✅ Cleanup Complete!

Before: 450 GB used (90%)
After:  385 GB used (77%)
━━━━━━━━━━━━━━━━━━━━━━━━
Recovered: 65 GB

Breakdown:
- System caches:        45 GB
- Downloads:            12 GB
- Homebrew cache:        5 GB
- Application remnants:  3 GB

⚠️ Notes:
- Some applications may take longer to launch on first run
- Deleted items cannot be recovered unless you have Time Machine backup
- Consider running this cleanup monthly

💡 Maintenance Tips:
- Set up automatic Homebrew cleanup: `brew cleanup` weekly
- Review Downloads folder monthly
- Enable "Empty Trash Automatically" in Finder preferences

安全ガイドライン

常に保持するもの

ユーザーから明示的な指示がない限り、次のものは削除しないでください。

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

sudo の確認が必要です

これらの操作には昇格した権限が必要です。ユーザーにコマンドを手動で実行するよう依頼してください。

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

プロンプトの例：

⚠️ This operation requires administrator privileges.

Please run this command manually:
  sudo rm -rf /Library/Caches/*

⚠️ You'll be asked for your password.

バックアップの推奨

10 GB を超えるクリーンアップを実行する前に、次のバックアップを推奨してください。

💡 Safety Tip:
Before cleaning XX GB, consider creating a Time Machine backup.

Quick backup check:
  tmutil latestbackup

If no recent backup, run:
  tmutil startbackup

トラブルシューティング

「操作は許可されていません」というエラー

SIP（システム整合性保護）により、macOS が一部のシステムファイルの削除をブロックする場合があります。

解決策：無理に削除しないでください。これらの保護はセキュリティのためにあります。

キャッシュ削除後にアプリがクラッシュする

まれに発生することがあります。解決策：アプリを再起動してください。必要なキャッシュは再生成されます。

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 - 開発環境のリソースをスキャンします
• safe_delete.py - 確認付きで対話的に削除します
• cleanup_report.py - クリーンアップ前後のレポートを生成します

references/

• cleanup_targets.md - 各クリーンアップ対象の詳細な説明
• mole_integration.md - このスキルと併せて Mole を使用する方法
• safety_rules.md - 絶対に削除してはいけないものの包括的な一覧

使用例

例 1：キャッシュのクイッククリーンアップ

ユーザーの依頼：「Mac の空き容量がなくなってきました。手伝ってもらえますか？」

ワークフロー：

1. 簡易診断を実行する
2. すぐに対処できる項目として、システムキャッシュを特定する
3. 調査結果を提示する：「~/Library/Caches に 45 GB あります」
4. 説明する：「これらは安全に削除できます。アプリが再生成します」
5. 確認を求める
6. 実行する：rm -rf ~/Library/Caches/*
7. 報告する：「45 GB の空き容量を回復しました」

例 2：開発環境のクリーンアップ

ユーザーの依頼：「開発者ですが、ディスクがいっぱいです」

ワークフロー：

1. scripts/analyze_dev_env.py を実行する
2. Docker、npm、Homebrew の調査結果を提示する
3. 各カテゴリを説明する
4. 説明を添えてクリーンアップコマンドを提示する
5. ユーザーに実行してもらう（Docker のクリーンアップは自動実行しない）
6. 結果を確認する

例 3：大きなファイルの検索

ユーザーの依頼：「こんなに容量を使っているのは何ですか？」

ワークフロー：

1. scripts/analyze_large_files.py --threshold 100MB を実行する
2. コンテキストを添えて、大きなファイルの上位 20 件を提示する
3. 動画、データセット、アーカイブ、ディスクイメージに分類する
4. 削除するものをユーザーに判断してもらう
5. 確認済みのファイルを削除する
6. 外付けドライブへのアーカイブを提案する

ベストプラクティス

1. 慎重に始める：明らかに安全な対象（キャッシュ、ゴミ箱）から始めます
2. すべて説明する：ユーザーが削除対象を理解できるようにします
3. 例を示す：各カテゴリからファイルの例を 3～5 件表示します
4. ユーザーのペースを尊重する：確認を急がせないでください
5. 結果を記録する：クリーンアップ前後の空き容量を必ず表示します
6. 知識を伝える：最終レポートにメンテナンスのヒントを含めます
7. ツールを連携する：GUI を好むユーザーには Mole を提案します

このスキルを使用しない場合

• ユーザーが自動または無言でのクリーンアップを希望している場合（安全第一の原則に反します）
• ユーザーが Windows／Linux のクリーンアップを必要としている場合（macOS 専用のスキルです）
• ディスク使用率が 10% 未満の場合（クリーンアップは不要です）
• SIP の無効化が必要なシステムファイルのクリーンアップを希望している場合（セキュリティ上のリスクがあります）

このような場合は、制限事項を説明し、代替案を提案してください。

---

注意点

• APFS スナップショットは rm では削除できません — tmutil deletelocalsnapshots を使用してください。df で解放されたバイト数を報告するクリーナーでも、スナップショットがブロックを保持しているため、変化が見られない場合があります。
• iCloud の「Optimize Mac Storage」は、クリーニングしたファイルを通知なしに再ダウンロードします — 除外するパスを許可リストに登録しないと、クリーナーがループします。
• TimeMachine のローカルスナップショットは、iCloud と同じブロックを取り合います — 競合の解決は非決定的です。「解放された」容量が1時間以内に再び使用される場合があります。
• /private/var/db/ のキャッシュは、理解せずにクリーニングしてはいけません — 再起動時に再構築されるもの（低コスト）もあれば、再インストールが必要なもの（高コスト）もあります。
• APFS では、クローンがあるため du と df の数値は大きく異なります — du は見かけ上のサイズを報告し、df は使用中のブロック数を報告します。どちらの数値も単独では信用しないでください。
• 隔離されたファイル（com.apple.quarantine xattr）：Gatekeeper を考慮せずに削除すると、この属性が再び付与される場合があります。一部のワークフローはループします。