config-gc

Config GC — Claude Code 配置垃圾回收

借用运行时垃圾回收的思路：定期扫描不再被引用、冗余、过期或低价值的对象，并回收空间。关键区别是：这里的回收必须有人参与。不要自治删除。

何时激活

• 用户要求清理、审计或瘦身 Claude Code 配置
• 用户抱怨 skills 太多、hooks 太吵或 session 启动慢
• 到了每月/定期 config review
• 安装大型 skill pack（例如本 repo）后，用来调和与既有配置的重叠

不要用于：清理项目源码（那是重构）、清空聊天历史或卸载 Claude Code 本身。

设计理念

1. Append-only configs 会泄漏。 Skills、memory files、hooks 和 permission entries 只会不断增加。不定期审查就会静默腐烂。
2. 定期审计胜过一次性清空。 每约 30 天扫描一次，每次提出一小批候选。
3. 按通道使用不同策略。 每种累积类型（skills、hooks、permissions 等）都有自己的过期信号，不要一条规则套全部。
4. 先软删除。 重命名为 .disabled > 移到 ~/.claude/_gc_trash/ > 真删除。始终保留 undo path。
5. 强制 human-in-the-loop。 每个候选都有自己的 [y/n/skip] 确认。没有 “yes to all” 捷径。
6. 保留日志。 每次 GC run 追加到 ~/.claude/gc_log.md：动了什么、为什么、如何撤销。

扫描通道

#	通道	路径	过期 / 冗余信号
1	Skills	~/.claude/skills/*/	名称高度重叠；近期 transcripts 从未触发；领域与用户实际工作不匹配；破损或空 SKILL.md
2	Memory	~/.claude/**/memory/*.md + index	同一主题多个 index entries；内容与更新条目矛盾；日期已过；index 缺失的 orphan files；应合并的低于 100 词片段
3	Hooks	~/.claude/hooks/ + settings	磁盘上有脚本但没有 hook config 引用；旧版本已被重写取代
4	Permissions	settings.json / settings.local.json 中的 permissions.allow	重复 entries；已被 wildcard 覆盖的具体条目（如已有 Bash(*) 时的 Bash(git push)）；过往实验的一次性授权
5	MCP servers	~/.claude.json 或项目 .mcp.json	无法连接的 servers；功能重复；长期不用
6	Scheduled reminders / jobs	用户存放位置	已触发的一次性任务超过 30 天；目标脚本已不存在的 jobs
7	Project history	~/.claude/projects/*/	陈旧 handoff snapshots；已被新状态取代的 session records
8	Runtime caches	cache/、file-history/、logs/、shell-snapshots/	按大小和 mtime 排序；建议清理超过 30 天且较大的项目

工作流

1. Scan 所有通道（或用户指定子集）。收集候选：path、channel、触发信号、size、last-modified。
2. Rank 按置信度排序（broken/orphaned = high；只是旧 = low），以编号表格展示。每次最多约 20 个候选——GC 是周期性的，不是穷尽式。
3. 逐项确认。 对每个候选显示证据，然后询问 [y/n/skip]。用户可以随时停止。
4. 软删除确认项：skills/hooks 优先 .disabled 重命名，文件移到 _gc_trash/<date>/。Permission entries 位于 JSON（不能写 comments）：备份 settings 文件，在 gc_log.md 中逐字记录每个 removed entry，然后用 jq 从 allow 数组删除。只有用户明确要求时才硬删除。
5. Log 到 ~/.claude/gc_log.md：timestamp、处理项、undo instructions。
6. Report：回收大小、仍健康的通道、建议下次审查日期。

示例扫描命令

孤立 hook scripts（channel 3）——磁盘上存在但没有 hook config 引用的 scripts：

for f in ~/.claude/hooks/*; do
  name=$(basename "$f")
  grep -rq "$name" ~/.claude/settings.json ~/.claude/settings.local.json 2>/dev/null \
    || echo "ORPHAN: $f"
done

冗余 permission entries（channel 4）——重复项，以及被 wildcard 遮蔽的具体授权：

jq -r '.permissions.allow[]' ~/.claude/settings.local.json | sort | uniq -d
if jq -e '.permissions.allow | index("Bash(*)")' ~/.claude/settings.local.json >/dev/null; then
  jq -r '.permissions.allow[]' ~/.claude/settings.local.json \
    | grep '^Bash(' | grep -vF 'Bash(*)'
fi

最大的陈旧 caches（channel 8）——使用 du -k 而不是 GNU-only find -printf，因此 macOS/BSD 也能用：

find ~/.claude/file-history ~/.claude/shell-snapshots -type f -mtime +30 \
  -exec du -k {} + 2>/dev/null | sort -rn | head -20

带 undo path 的软删除（只捕获一次日期，避免日志和目录不一致）：

gc_date=$(date +%Y-%m-%d)
mkdir -p ~/.claude/_gc_trash/$gc_date
mv ~/.claude/skills/dead-skill ~/.claude/_gc_trash/$gc_date/
echo "$(date -Iseconds) moved skills/dead-skill -> _gc_trash/$gc_date/ (undo: mv back)" >> ~/.claude/gc_log.md

删除已确认冗余的 permission entry（JSON 无 comments——先备份、记录，再编辑）：

cp ~/.claude/settings.local.json ~/.claude/settings.local.json.bak
echo "$(date -Iseconds) removed permission entry: Bash(git push) (undo: restore from .bak or re-add)" >> ~/.claude/gc_log.md
jq '.permissions.allow -= ["Bash(git push)"]' ~/.claude/settings.local.json.bak \
  > ~/.claude/settings.local.json

反模式

• 批量批准。 问“delete all 15? [y/n]”违背设计。一个项目，一个决定。
• 第一轮硬删除。 没有 _gc_trash/ 副本或 .disabled 重命名，就是做错了。
• 把“旧”当成“死”。 一个 60 天没用的 skill 可能是季节性需求（税季、季度复盘）。年龄是信号，不是结论——这就是为什么需要人确认。
• 靠截断清理 memory。 合并两个矛盾 memory files 需要读两者并保留更新事实，不是删除更长的那个。
• 触碰 ~/.claude 外的任何东西（或项目 .claude/）。Config GC 不会跑进源码树。

最佳实践

• 大量新增后运行，而不只是按日历运行：安装 50-skill pack 正是与现有 skills 产生重叠的时候。
• 两个 skills 重叠时，优先禁用 trigger description 较弱的那个——它大概率本来就不会触发。
• Permission cleanup 是单位时间价值最高的通道：冗余 allow-entries 会让安全审查更难。
• 永久保留 gc_log.md。它很小，而“我什么时候禁用了那个 hook，为什么”比你想的更常出现。

相关技能

• skill-stocktake — 审计 skill 质量；config-gc 审计 skill 是否应存在。对 GC 后保留下来的运行 stocktake。
• workspace-surface-audit — 加法侧：建议安装什么。config-gc 是同一生命周期的减法半边。
• configure-ecc — 用它安装 skills 后，运行 config-gc 来调和与既有配置的重叠。
• continuous-learning — 产生此技能后续审计的 memory files。
• security-review — 与 permissions 通道搭配很好。