config-gc (Coleta de Lixo para Configuração do Claude Code)

Config GC — Coleta de Lixo para Configurações do Claude Code

Inspirado na coleta de lixo em tempo de execução: escanear periodicamente objetos que não são mais referenciados, redundantes, expirados ou de baixo valor e recuperar espaço. A diferença crítica: aqui, a coleta requer um humano no loop. Nunca delete autonomamente.

Quando Ativar

• O usuário pede para limpar, auditar ou reduzir sua configuração do Claude Code
• O usuário reclama de muitas skills, hooks barulhentos ou inicialização lenta da sessão
• Uma revisão periódica/mensal da configuração está devida
• Após instalar um pacote grande de skills (ex.: este repositório), para reconciliar sobreposições com a configuração existente

NÃO ativar para: limpar código-fonte do projeto (isso é refatoração), limpar histórico de chat ou desinstalar o próprio Claude Code.

Filosofia de Design

1. Configurações somente anexadas vazam. Skills, arquivos de memória, hooks e entradas de permissão só são adicionados. Sem revisão periódica, eles apodrecem silenciosamente.
2. Auditorias regulares superam purgas únicas. Escaneie a cada ~30 dias, proponha um pequeno lote de candidatos de cada vez.
3. Estratégias por canal. Cada tipo de acúmulo (skills, hooks, permissões, ...) tem seus próprios sinais de obsolescência — não aplique uma regra em todos os lugares.
4. Soft-delete primeiro. Renomeie para .disabled > mova para ~/.claude/_gc_trash/ > exclusão real. Sempre mantenha um caminho de desfazer.
5. Humano no loop forçado. Cada candidato tem sua própria confirmação [y/n/skip]. Sem atalho "sim para todos".
6. Mantenha um registro. Cada execução de GC anexa a ~/.claude/gc_log.md: o que foi tocado, por que e como desfazer.

Canais de Varredura

#	Canal	Caminho	Sinais de obsolescência / redundância
1	Skills	~/.claude/skills/*/	Nomes com forte sobreposição; nunca acionados em transcrições recentes; incompatibilidade de domínio com o trabalho real do usuário; SKILL.md quebrado ou vazio
2	Memória	~/.claude/**/memory/*.md + seu índice	Múltiplas entradas de índice para um tópico; conteúdo contradizendo entradas mais recentes; datas passadas; arquivos órfãos ausentes do índice; fragmentos com menos de 100 palavras que deveriam ser mesclados
3	Hooks	~/.claude/hooks/ + configurações	Scripts presentes no disco, mas não referenciados por nenhuma configuração de hook; versões antigas substituídas por reescritas
4	Permissões	permissions.allow em settings.json / settings.local.json	Entradas duplicadas; entradas específicas já cobertas por um curinga (ex.: Bash(git push) quando Bash(*) é permitido); concessões pontuais de experimentos passados
5	Servidores MCP	~/.claude.json ou .mcp.json do projeto	Servidores que falham ao conectar; duplicatas funcionais; não utilizados há muito tempo
6	Lembretes / tarefas agendadas	onde quer que o usuário os mantenha	Disparos únicos com mais de 30 dias; tarefas cujos scripts de destino não existem mais
7	Histórico de projetos	~/.claude/projects/*/	Snapshots de handoff obsoletos; registros de sessão substituídos por estado mais recente
8	Caches de tempo de execução	cache/, file-history/, logs/, shell-snapshots/	Ordene por tamanho e mtime; proponha itens com mais de 30 dias e grandes

Fluxo de Trabalho

1. Varra todos os canais (ou o subconjunto que o usuário nomear). Colete candidatos com: caminho, canal, sinal que o sinalizou, tamanho, última modificação.
2. Classifique por confiança (quebrado/órfão = alta; apenas antigo = baixa) e apresente como uma tabela numerada. Limite cada execução a ~20 candidatos — GC é periódico, não exaustivo.
3. Confirme um por um. Para cada candidato, mostre a evidência e pergunte [y/n/skip]. O usuário pode parar a qualquer momento.
4. Soft-delete itens confirmados: prefira renomear com .disabled para skills/hooks e mover para _gc_trash/<data>/ para arquivos. Entradas de permissão vivem em JSON (sem comentários possíveis): faça backup do arquivo de configurações, registre cada entrada removida textualmente em gc_log.md e remova-a do array allow com jq. Exclusão definitiva apenas quando o usuário solicitar explicitamente.
5. Registre a execução em ~/.claude/gc_log.md: timestamp, itens processados, instruções de desfazer.
6. Relate: tamanho recuperado, canais ainda saudáveis, data sugerida para próxima revisão.

Exemplos de Comandos de Varredura

Scripts de hook órfãos (canal 3) — scripts no disco que nenhuma configuração de hook referencia:

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

Entradas de permissão redundantes (canal 4) — duplicatas e concessões específicas ofuscadas por um curinga:

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

Maiores caches obsoletos (canal 8) — du -k em vez do exclusivo GNU find -printf, para funcionar também em macOS/BSD:

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

Soft-delete com caminho de desfazer (capture a data uma vez para que o registro não possa discordar do diretório):

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/ (desfazer: mv de volta)" >> ~/.claude/gc_log.md

Removendo uma entrada de permissão confirmada como redundante (JSON não tem comentários — faça backup, registre e edite):

cp ~/.claude/settings.local.json ~/.claude/settings.local.json.bak
echo "$(date -Iseconds) removed permission entry: Bash(git push) (desfazer: restaurar de .bak ou readicionar)" >> ~/.claude/gc_log.md
jq '.permissions.allow -= ["Bash(git push)"]' ~/.claude/settings.local.json.bak \
  > ~/.claude/settings.local.json

Anti-Padrões

• Aprovação em lote. Perguntar "deletar todos os 15? [y/n]" derrota o design. Um item, uma decisão.
• Exclusão definitiva na primeira passagem. Se não houver cópia em _gc_trash/ ou renomeação para .disabled, você fez errado.
• Tratar "antigo" como "morto". Uma skill não tocada por 60 dias pode ser sazonal (temporada de impostos, revisões trimestrais). Idade é um sinal, não um veredito — é por isso que um humano confirma.
• Limpar memória por truncamento. Mesclar dois arquivos de memória contraditórios requer ler ambos e manter a verdade mais recente, não deletar o mais longo.
• Tocar qualquer coisa fora de ~/.claude (ou do .claude/ do projeto). Config GC nunca vagueia por árvores de código-fonte.

Melhores Práticas

• Execute após grandes adições, não apenas em um calendário: instalar um pacote de 50 skills é exatamente quando a sobreposição com skills existentes aparece.
• Quando duas skills se sobrepõem, prefira desativar aquela com a descrição de gatilho mais fraca — é a que provavelmente nunca estava disparando de qualquer maneira.
• A limpeza de permissões é o canal de maior valor por minuto gasto: entradas allow redundantes dificultam a revisão de segurança.
• Mantenha gc_log.md para sempre. É pequeno, e "quando desativei aquele hook e por quê" aparece mais do que você imagina.

Skills Relacionadas

• skill-stocktake — audita a qualidade das skills; config-gc audita a existência das skills. Execute stocktake no que sobreviver ao GC.
• workspace-surface-audit — a contraparte aditiva: recomenda o que instalar. config-gc é a metade subtrativa do mesmo ciclo de vida.
• configure-ecc — após instalar skills com ele, execute config-gc para reconciliar sobreposições com sua configuração pré-existente.
• continuous-learning — produz os arquivos de memória que esta skill audita posteriormente.
• security-review — combina bem com o canal de permissões.