長くAI Agentを走らせると、作業ディレクトリを開いたときによくこうなります。一時ファイル、定期taskのログ、スクリーンショット、古い記憶メモがディレクトリ全体に積み上がる。手で20分清掃しても、翌日にはまた生えます。
これは構造的な問題です。AI Agentのworkspaceは自然に膨張します。各sessionが一時ファイルを作り、各定期taskがログを残し、各メディアtaskがスクリーンショットを出す。自動清掃機構がなければ、エントロピーとの負け戦です。
中核理念：scriptが力仕事をし、AIが判断する
このシステムを設計する前に、「全部AIに清掃させる」を試しました。結果はこうです。
| 方法 | コスト | 問題 |
|---|---|---|
| 全部手作業で清掃 | お金はかからないが時間がかかる | 毎日10-20分、忘れやすい |
| 全部AIに任せる | 毎回tokenを払う | 多くの清掃は判断力を必要としない |
| script + AIの混合 | 1回あたりのコストが非常に低い | scriptが決定的な仕事を処理し、判断が必要なときだけAIが入る |
中核原則：
「3日を超えた一時ファイルを消す」にAI判断は不要です。shell scriptで十分です。 「この2つの記憶メモは80%重複している。統合するか？」にはAIが必要です。
4層アーキテクチャ
graph TD
T0["⏱ Tier 0：毎時の健康チェック<br/>純粋なShell"] --> T1["🧹 Tier 1：毎日の清掃<br/>純粋なShell"]
T1 --> T2["🔍 Tier 2：毎週のscan<br/>Shell + AI"]
T2 --> T3["📋 Tier 3：毎月の監査<br/>Shell + AI"]| Tier | 頻度 | 実行者 | 内容 |
|---|---|---|---|
| 0 | 毎時 | Shell | 健康チェック、sentinel監視、エラー重複除去 |
| 1 | 毎日 | Shell | 一時ファイル、メディア、ログを清掃 |
| 2 | 毎週 | Shell + AI | topic file精製、メモ圧縮 |
| 3 | 毎月 | Shell + AI | 環境manifest比較、複雑度監査 |
上に行くほど頻度は低く、必要な判断力は高く、コストも高くなります。「N日前の一時ファイルを消す」までAIに任せると、長期的なtoken代がディスク容量より高くなります。
Tier 0：毎時の健康チェック
システム全体のheartbeatです。何も清掃せず、3つだけ行います。
1. Sentinelファイルチェック
各Tierが実行完了後、「sentinel file」を更新します。
# Tier 1完了時に書き込む
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) OK" > .last-daily-ok
# Tier 0がsentinelを確認する
last_daily=$(cat .last-daily-ok 2>/dev/null)
# 36時間を超えて更新されていなければ → 警告スケジューラー自体が正常かどうかを監視する必要はありません。sentinel fileが十分新しいかを見れば、全体が動いているか分かります。
2. エラー重複除去
同じ警告は連続して複数回出たときだけ通知します。通知疲れを避けるためです。毎時「一時ファイルがN個を超えています」と届くと、すぐ全警告を無視するようになります。
3. 早期終了
workspaceがきれいで、閾値超過ファイルもsentinel欠落もない場合、script全体は数ミリ秒で終了します。不要なscanはしません。
Tier 1：毎日の清掃
実際に清掃が始まる場所です。すべてのルールは決定的です。判断は不要で、年齢と種類だけを見ます。
清掃ルール
| 対象 | ルール | デフォルト閾値 |
|---|---|---|
一時ファイル（tmp/） | N日を超えたら削除 | 3日 |
メディアファイル（media/） | N日を超えたら削除 | 7日 |
定期taskログ（cron/runs/） | N日を超えたら削除 | 14日 |
| 空ディレクトリ | 自動削除 |
2層の早期終了
Tier 1の重要設計は2層の早期終了です。
# 第1層：全体チェック
total_candidates=$(find tmp/ media/ cron/runs/ -type f | wc -l)
if [ "$total_candidates" -eq 0 ]; then
echo "Nothing to clean. Exiting."
exit 0
fi
# 第2層：カテゴリごとに個別チェック
old_temps=$(find tmp/ -mtime +3 -type f | wc -l)
if [ "$old_temps" -eq 0 ]; then
echo "tmp/ is clean. Skipping."
# 次のカテゴリへ進む。script全体は終了しない
fiこれにより、きれいなworkspaceではほぼI/Oを使いません。
安全な削除
すべての削除はrmではなく、macOSではtrashを使い、後悔できる期間を残します。trashコマンドがない場合、scriptは~/.Trash/へ移動するfallbackを使います。
Tier 2：毎週のAI補助scan
ここから判断力が必要になります。Shell scriptはデータ収集、AIは判断を担当します。
Scriptがやること
- すべてのtopic fileと最終更新日を列挙
- 各プロジェクトディレクトリのサイズを計算
- 他ファイルと高重複のメモを探す
- 長期間動いていないプロジェクトを列挙
AIがやること
scan reportを受け取った後、AIが判断します。
- この2つのメモは80%重複。統合する？→ 統合
- このプロジェクトは30日動いていない。一時停止か終了か？→ 一時停止としてマーク
- このtopic fileは200行を超えている。分割する？→ 分割
なぜこの分担か
Shell scriptによるデータ収集はほぼ無料です（ミリ秒単位）。AIの判断1回も低コストです。AI自身にscanさせると、数十個のファイルを読む必要があり、それぞれがtokenになってコストが何倍にも膨らみます。
scriptで先に絞り、AIは要点だけを見る。 これでシステム全体の週次AIコストをかなり低く抑えられます。
Tier 3：毎月の深度監査
月1回、全面的な健康診断を行います。
環境Manifest
毎月、環境snapshotを作ります。
## 環境Manifest：2026-03
- プロジェクト数：N（先月 M、差分）
- 記憶メモ：N（先月 M、差分）
- topic file：N（先月 M、差分）
- 定期task：N（先月 M、差分）
- 総ディスク使用量：X GB（先月 Y GB、差分）前月と比べれば、どこが膨らみ、どこが縮んでいるか分かります。
複雑度の罠
メンテナンスシステム自体も膨らみます。毎月の監査では以下を見ます。
- 清掃ルールが増えすぎていないか？（閾値を超えたら簡素化）
- scriptが長くなりすぎていないか？（行数閾値を超えたら分割）
- 「メンテナンスシステムのメンテナンスシステム」を維持していないか？（一歩下がるタイミング）
Feedback Loop：システムが自分で進化する
このシステムの面白い設計は自動改善機構です。
- Tier 1が異常を見つける：「5日連続で10個以上の一時ファイルを清掃。閾値が長すぎるかも？」→
optimization-suggestions.mdへ書く - Tier 2が提案を評価：AIが提案を読み、妥当か判断
- Tier 3がルール採用：AIと人間の両方が認めたら、
config.shの閾値を更新
システムが自分の運用経験から学びます。「前回どう調整したか」を人が毎回覚える必要はありません。
失敗から学んだこと
scriptに書く前にぶつかった壁です。
null-byte bug
一部のAIツールは、ときどきファイルにnull bytes（\x00）を書き込みます。ファイルは普通に見えますが、grepはbinary fileとして扱いskipします。解法：清掃時にnull-byte scanを入れる。
-newermtの罠
macOSのfindは-newermtをサポートしません。解法：-mtime +Nを使うか、stat -f%mでepoch timeを取り自分で計算する。各platform差分はconfig.shのhelper functionに閉じ込めます。
早期終了の価値
最初は早期終了がなく、毎時の健康チェックに2-3秒かかっていました。早期終了を入れた後、きれいなworkspaceでは数十ミリ秒です。小さく聞こえますが、1日24回積み上がると差はかなりあります。
Quick Start
必要なのは4つだけです。
1. Clone + path設定
git clone https://github.com/p3nchan/auto-optimization.git
cd auto-optimization
export WORKSPACE_ROOT="$HOME/.my-agent-workspace"2. 閾値を調整
config/config.shを編集します。
THRESHOLD_TEMP_DAYS=3 # 一時ファイルの保持日数
THRESHOLD_MEDIA_DAYS=7 # メディアファイルの保持日数
THRESHOLD_CRON_LOG_DAYS=14 # 定期taskログの保持日数3. スケジューリング
# crontab -e
0 * * * * /path/to/auto-optimization/scripts/hourly-healthcheck.sh
0 3 * * * /path/to/auto-optimization/scripts/daily-cleanup.sh
0 4 * * 0 /path/to/auto-optimization/scripts/weekly-scan.sh
0 5 1 * * /path/to/auto-optimization/scripts/monthly-scan.sh4. 観察
数日走らせたら、optimization-suggestions.mdに提案が溜まっているか見ます。その提案に合わせて閾値を調整します。
まとめ
| 状況 | 推奨 |
|---|---|
| AI Agentを使い始めたばかり | まずTier 1（毎日の清掃）だけで十分 |
| 複数プロジェクトが動いている | Tier 0（健康チェック）+ Tier 1を追加 |
| 定期task + 大量ログがある | 4層すべてを使う |
| 最小投入だけしたい | daily-cleanup.shをcronに入れ、他は後回し |
完全なscript、設定ファイル、文書はopen-source repoにあります。
MITライセンスです。cloneして少し直せば使えます。
関連記事
よくある質問
Q: なぜAI Agentのworkspaceに自動清掃が必要ですか？
AI Agentは各sessionで一時ファイル、ログ、スクリーンショットなどを作ります。複数プロジェクトと定期taskが毎日走るworkspaceでは、ファイル数がすぐ膨らみます。定期的に清掃しないと、ディスク容量を浪費するだけでなく、AIのファイル検索も遅くなり、混乱しやすくなります。
Q: なぜ全部AIに清掃させないのですか？
AIの判断には毎回コスト（API token）がかかります。一方、清掃作業の大半は決定的です。N日を超えた一時ファイルを消す、N日を超えたログを消す、という作業はshell scriptで無料・高速・安定に処理できます。AIに渡すべきなのは、このメモはまだ必要か、2つのファイルを統合してよいか、のような判断が必要な少数の作業だけです。
Q: このシステムに必要な前提は何ですか？
bashとcron、または任意のスケジューラーだけです。macOSとLinuxの両方で動きます。AI補助のTier 2とTier 3は任意です。Tier 0とTier 1だけ、つまり純shellだけでもworkspace hygieneは大きく改善します。
こぺんぎんの体験談
OpenClaw上では、完全な3層自動最適化ループを走らせたことがあります。daily cronで清掃scriptを走らせ、weekly cronでlogからpatternを探してoptimization-suggestions.mdに書き、monthlyで初めて人間がreviewして、提案を正式ルールへ昇格するか判断します。実戦でよく踏む落とし穴は2つです。第一に、閾値が厳しすぎると有用な一時ファイルを何度も誤削除します。第二に、dry-run modeを書かずに削除を直接走らせると、最初の週で何かを失います。最初は見るだけで消さない観察段階から始め、2週間分布を見てから動作を有効にするのがおすすめです。
— Penchan