settings-optimize

settings-optimize — settings.json 整理 (dry-run + 明示 apply)

cost-optimizer plugin で唯一 write を含む skill。 4 段防御 (dry-run → backup → atomic write → auto-restore on failure) で安全に settings.json をクリーンアップする。

実行手順

1. dry-run (既定、 必ず最初にこれ)

bash "${CLAUDE_PLUGIN_ROOT}/scripts/settings-optimizer.sh" --dry-run

出力:

• 削除候補リスト (Stale Bash / Broken hooks / Env keys)
• 変更前後の unified diff

ユーザーに diff 提示 → ユーザーが「OK / NG」を判断。

2. apply (ユーザー明示確認後のみ)

bash "${CLAUDE_PLUGIN_ROOT}/scripts/settings-optimizer.sh" --apply

--apply を起動すると:

1. dry-run 同等の report 表示
2. interactive prompt: Apply these changes? [y/N]
3. y 確定後にのみ backup → atomic write → 検証
4. 検証失敗 (jq parse error) なら自動 restore + exit code 3

CI / 非対話環境で interactive を skip したい場合のみ:

FORCE_APPLY=1 bash "${CLAUDE_PLUGIN_ROOT}/scripts/settings-optimizer.sh" --apply

警告: FORCE_APPLY=1 は確認を skip する。 production settings (~/.claude/settings.json) には使うな。 sandbox / test 環境のみ。

3. 受講者向けエクスポート (sanitize 済 markdown)

bash "${CLAUDE_PLUGIN_ROOT}/scripts/settings-optimizer.sh" --dry-run --export ~/share/

./share/settings-optimizer-<timestamp>.md が出力。 個人 path / token / repo 名は redact 済。 settings.json 本体は export しない (個人 env / 絶対 path 過多のため)。

4. 詳細 option

flag	用途
--settings PATH	対象 settings.json を上書き (default: .claude/settings.json → ~/.claude/settings.json)
--since N	stale window を N 日に上書き (default 30、STALE_WINDOW_DAYS env でも可)
--export DIR	sanitize 済 markdown 出力先
--allow-truncated-scan	jsonl scan が truncated (= SCAN_FILE_LIMIT 超過) のとき --apply の 拒否を解除 する明示 override。 default は拒否 (= exit 1) で false-positive 削除を予防。 truncated 時に --apply を強行する場合は (1) SCAN_FILE_LIMIT を上げる、(2) どうしても override したい場合のみ本 flag を付ける

検出ルール

Stale Bash permissions

• permissions.allow[] 内の Bash(...) パターンを抽出
• 直近 STALE_WINDOW_DAYS (default 30) 日の jsonl から実 Bash 起動 command を抽出
• いずれにもマッチしないパターンを「削除候補」
• JSONL signal が一切無い (新規環境など) は全件 keep + warning

Broken hook references

• hooks.{event}[].hooks[].command の path を解析
• 検証対象外 (resolve 不能なため検出 skip):
  • ${CLAUDE_PLUGIN_ROOT} / $CLAUDE_PLUGIN_ROOT 始まり (Claude Code runtime 外で resolve 不能)
  • ${CLAUDE_PROJECT_DIR} / $CLAUDE_PROJECT_DIR も env 未設定時は resolve 不能 → path-like 判定にも該当せず検出 skip。env 設定環境では展開されて検出対象となる
• 絶対 path / 相対 path (/, ./, ../ 始まり) で [ ! -e "$path" ] のものを「削除候補」

Env vars (情報のみ)

• env.{key} を全列挙
• jsonl からは 使用判定不可 (env は process start 時 read で tool_use に出ない)
• 「未検証」として情報表示、 自動削除はしない

4 段防御の中身

段階	内容	失敗時
1. dry-run	diff のみ、 write なし	影響なし
2. backup	settings.json.bak.<nanosec or unix-pid-rand> 高精度 suffix で並列衝突回避	cp 失敗 → exit 3、 apply 中止
3. atomic write	mktemp で同 dir に staging → cp $proposed → $tmp → mv $tmp $settings (atomic)	各段で戻り値検査、 失敗時 backup から auto-restore
4. verify + restore	post-write jq empty parse 検証	parse 失敗 → backup を上書き restore、 restore 失敗時は明示 abort + backup path 表示

Scope-merge advisory

Claude Code は permissions.allow 等の array を scope 間 (managed > CLI > local > project > user) で concatenate + dedupe する。 1 scope のファイルから permission を消しても、 他 scope に同じ entry があれば実効的に有効のまま。

settings-optimizer は dry-run / apply 両方で「他 scope に同 entry あり」を grep し、 該当があれば ## Scope-merge advisory セクションを report に出力する。 該当 scope 全部に対して個別に optimizer を走らせるのが正しい cleanup フロー。

注意

• skill 自体は read-only (script 起動だけ)。 write は --apply 経由でのみ発生。
• backup は 削除しない。 user が古い backup を整理する。
• protected paths (.claude/settings.json) は Claude Code 標準で write prompt 強制 → user 確認が二重に効く。

関連 skill / plugin

• cost-monitor の cost-status: optimization の cost 影響評価
• skill-analyzer の improvement-proposal: skill / MCP の削除候補もこちらで
• agent-recommend / model-recommend (同 plugin): 推奨ベースの settings 微調整に