# Claude Code の `/clear` でセッション一覧が汚れる問題を根絶する
VSCode 拡張（および CLI）で `/clear` を多用すると、セッション履歴が「中身のない残骸」で埋まり、
さらに「押したか分からず何度も押す」という体験の悪化が起きる。この指示書はその3つの原因を分離して
機械的に潰す手順。AI エージェントに読ませればそのまま実装できる。
## 前提の理解（ここを間違えると対策を誤る）
1. **`/clear` は履歴の削除コマンドではない。** 「会話文脈をリセットして新しいセッションを始める」機能。
だからセッション一覧からは何も消えない。一覧から消す操作は各行の**ゴミ箱アイコン**（下記の通り
「非表示化」であって実体削除ではない）。
2. **`/clear` は押すたびに残骸セッションを1件作る。** そのセッションの JSONL には `/clear` の
コマンド記録（`/clear` 等）しか入っていない。数KB・実発言0件・応答0件。
3. **拡張のゴミ箱アイコンは実体を消さない。** セッション ID を「非表示リスト」に足すだけで、
JSONL は `~/.claude/projects/<プロジェクトdir>/.jsonl` に残り続ける。
4. **hook が返す文字列は VSCode 拡張の UI に描画されない。** `statusLine` 設定もスキーマ上は
受理されるが webview 側に描画実装が無い（拡張の bundle を `grep -o "statusLine[A-Za-z]*"` で
確認できる: extension.js に数件ヒット / webview に0件）。**可視化したいなら「AI の応答に言わせる」しかない。**
## 対策1: 残骸セッションを自動で一覧から外す（掃除の自動化）
常駐スクリプト（Python/Node どちらでもよい）を 30 秒間隔で回し、次の条件を全て満たす JSONL を
`~/.claude/projects/_deleted-backup/_empty/` へ **move（削除ではなく退避）** する。
- ファイルサイズが小さい（例: 200KB 未満。大きいものは読まずに除外して誤検出と I/O を防ぐ）
- `type` が `user` / `assistant` の行のうち、**本文が空でないものが0件**
（`` `` `` のようなコマンド記録は「発言」に数えない。
1件でも実発言・実応答を見つけた時点で即 false を返す＝早期打ち切り）
- **最終更新から一定時間が経っている**
最後の「猶予時間」の設計がキモ:
| 対象 | 猶予 | 理由 |
|---|---|---|
| 通常のセッション（実発言あり） | 600 秒 | 書き込み中・稼働中を絶対に触らないため長めに取る |
| **空の残骸セッション** | **90 秒** | 実発言0・応答0で失う情報が無く、実体も退避先に保全されるので長く待つ意味がない |
同じ猶予を使い回すと「10分間は残骸が一覧に居座る」＝人間には「消えていない」と体験される。
**空セッション専用の短い閾値を別定数で持たせる**こと。
実装メモ:
- 退避先は「バックアップ」であり削除ではない。復元できる形を保つ（過去のセッションは資産）。
- スクリプトを書き換えたら**常駐プロセスの再起動が必須**（起動時のコードを保持するため）。
再起動手順は「heartbeat ファイルの PID を kill → heartbeat を削除 → 再起動」。heartbeat を消さないと
「最近生きている」と誤判定して再起動がスキップされることがある。
- 単一インスタンス保証は heartbeat ファイル（PID + mtime による stale 判定）で行う。
## 対策2: `/clear` したことを可視化する（二重押しの防止）
多くのエージェント CLI には **SessionStart 系の hook に「起動理由」のマッチャ**があり、
`/clear` 由来の起動だけで発火させられる（例: matcher に `clear` を指定）。UI に描画されないので、
**hook の出力で「応答の1行目に必ず印を出せ」とエージェント自身に指示する**のが唯一効く経路。
hook スクリプトの骨子（Node、依存ゼロ）:
```js
#!/usr/bin/env node
import fs from "node:fs"; import os from "node:os"; import path from "node:path";
let sid = "";
try { sid = JSON.parse(fs.readFileSync(0, "utf8") || "{}").session_id || ""; } catch {}
const hhmm = new Date().toLocaleTimeString("ja-JP", { hour: "2-digit", minute: "2-digit" });
try {
fs.writeFileSync(path.join(os.homedir(), ".claude", "last-clear.json"),
JSON.stringify({ at: new Date().toISOString(), session_id: sid }, null, 2));
} catch {}
process.stdout.write(
`【/clear 直後のセッション】${hhmm} に /clear が実行され、この会話は文脈ゼロの新セッション。` +
`最初の応答の1行目に必ず \`🧹 /clear 済み（${hhmm}）\` と表示せよ（省略禁止）。\n`);
```
- stdin が空でも落ちないようにする（hook の呼ばれ方は環境差がある）。
- 時刻をファイルにも残すと「本当に発火したか」の診断ができる。
- 効果: 印が出れば実行済み、出なければ未実行と判断できるので**同じ操作を繰り返さなくなる**。
## 対策3: そもそも `/clear` を使わない（推奨）
VSCode 拡張には「新しい会話」コマンドがあり、**キーボードショートカット（Ctrl/Cmd+N）は既定で無効**。
ユーザー設定で有効化する:
```json
{ "claudeCode.enableNewConversationShortcut": true }
```
これで Claude パネルにフォーカスして Ctrl+N を押すと新しい会話が開く。利点:
- **画面が明示的に切り替わる**ので「押したか分からない」が構造的に起きない（＝二重押し不能）
- `/clear` のような**コマンド記録だけの残骸セッションが作られない**
- 設定変更の反映はウィンドウの再読み込み（`Developer: Reload Window`）または次回起動時
## 導入後の検証（ここまでやって初めて「直った」と言える）
1. 掃除スクリプトを**1回パスで実際に実行**し、ログに「残骸を退避した」旨が出ることを確認する。
2. **稼働中セッションの JSONL が無傷**であることをサイズ・mtime で確認する（最重要の退行チェック）。
3. 常駐プロセスが生きていることを PID で確認する（heartbeat の PID がプロセス一覧に居るか）。
4. 可視化 hook は `echo '{"session_id":"test"}' | node ` で単体実行し、出力文字列を目視する。
5. UI 側の見え方（印が出るか、ショートカットが効くか）だけは人間の1回確認に残る。ここは正直に伝える。
## 落とし穴
- 「一覧から消えない」を `/clear` の不具合と誤診しない。**仕様**であり、原因は別（残骸の蓄積・非表示化の仕組み）。
- 猶予時間を一律に長く取ると「消えない」体験が残る。逆に一律に短くすると稼働中セッションを触る危険がある。**対象別に分ける。**
- 残骸を**削除**しない。退避（move）にする。誤検出時に戻せる状態を必ず残す。
- スクリプト修正後の常駐再起動を忘れると「直したのに直っていない」になる。
---