config-gc

Config GC — Recolección de Basura para Configuraciones de Claude Code

Tomado de la recolección de basura en tiempo de ejecución: escanea periódicamente objetos que ya no son referenciados, redundantes, caducados o de bajo valor, y recupera el espacio. La diferencia crítica: aquí, la recolección requiere un humano en el circuito. Nunca borrar de forma autónoma.

Cuándo activarlo

• El usuario pide limpiar, auditar o reducir su configuración de Claude Code
• El usuario se queja de demasiadas skills, hooks ruidosos o inicio de sesión lento
• Ha llegado el momento de una revisión mensual/periódica de la configuración
• Después de instalar un paquete grande de skills (p. ej., este repositorio), para conciliar superposiciones con la configuración existente

NO activar para: limpiar código fuente del proyecto (eso es refactorización), borrar historial de chat o desinstalar Claude Code en sí.

Filosofía de diseño

1. Las configuraciones solo agregables tienen fugas. Las skills, archivos de memoria, hooks y entradas de permisos solo se añaden. Sin revisión periódica, se pudren en silencio.
2. Las auditorías regulares superan a las purgas únicas. Escanear cada ~30 días, proponer un pequeño lote de candidatos cada vez.
3. Estrategias por canal. Cada tipo de acumulación (skills, hooks, permisos, ...) tiene sus propias señales de obsolescencia: no aplicar una sola regla en todas partes.
4. Soft-delete primero. Renombrar a .disabled > mover a ~/.claude/_gc_trash/ > borrado real. Mantener siempre una ruta de deshacer.
5. Humano en el circuito forzado. Cada candidato recibe su propia confirmación [y/n/skip]. No hay acceso directo de "sí a todo".
6. Mantener un registro. Cada ejecución de GC añade a ~/.claude/gc_log.md: qué se tocó, por qué y cómo deshacerlo.

Canales de escaneo

#	Canal	Ruta	Señales de obsolescencia / redundancia
1	Skills	~/.claude/skills/*/	Nombres muy superpuestos; nunca activados en transcripciones recientes; desajuste de dominio con el trabajo real del usuario; SKILL.md roto o vacío
2	Memoria	~/.claude/**/memory/*.md + su índice	Múltiples entradas de índice para un mismo tema; contenidos que contradicen entradas más nuevas; fechas que ya han pasado; archivos huérfanos faltantes del índice; fragmentos de menos de 100 palabras que deberían fusionarse
3	Hooks	~/.claude/hooks/ + configuraciones	Scripts presentes en disco pero no referenciados por ninguna configuración de hook; versiones antiguas reemplazadas por reescrituras
4	Permisos	permissions.allow en settings.json / settings.local.json	Entradas duplicadas; entradas específicas ya cubiertas por un comodín (p. ej., Bash(git push) cuando Bash(*) está permitido); concesiones únicas de experimentos pasados
5	Servidores MCP	~/.claude.json o .mcp.json del proyecto	Servidores que fallan al conectar; duplicados funcionales; no usados por mucho tiempo
6	Recordatorios / tareas programadas	donde sea que el usuario los mantenga	Disparos únicos mayores de 30 días; tareas cuyos scripts objetivo ya no existen
7	Historial de proyectos	~/.claude/projects/*/	Instantáneas de transferencia obsoletas; registros de sesión reemplazados por estado más nuevo
8	Cachés de ejecución	cache/, file-history/, logs/, shell-snapshots/	Ordenar por tamaño y mtime; proponer elementos >30 días de antigüedad y grandes

Flujo de trabajo

1. Escanear todos los canales (o el subconjunto que nombre el usuario). Recopilar candidatos con: ruta, canal, señal que lo marcó, tamaño, última modificación.
2. Ordenar por confianza (roto/huérfano = alto; simplemente antiguo = bajo) y presentar como una tabla numerada. Limitar cada ejecución a ~20 candidatos — GC es periódico, no exhaustivo.
3. Confirmar uno por uno. Para cada candidato mostrar la evidencia, luego preguntar [y/n/skip]. El usuario puede detenerse en cualquier momento.
4. Soft-delete de elementos confirmados: preferir renombrar a .disabled para skills/hooks y mover a _gc_trash/<fecha>/ para archivos. Las entradas de permisos viven en JSON (sin comentarios posibles): hacer copia de seguridad del archivo de configuración, registrar cada entrada eliminada textualmente en gc_log.md, luego eliminarla del arreglo allow con jq. Solo borrar definitivamente cuando el usuario lo solicite explícitamente.
5. Registrar la ejecución en ~/.claude/gc_log.md: marca de tiempo, elementos accionados, instrucciones para deshacer.
6. Informar: tamaño recuperado, canales aún saludables, fecha sugerida de próxima revisión.

Comandos de escaneo de ejemplo

Scripts de hook huérfanos (canal 3) — scripts en disco que ninguna configuración 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 "HUÉRFANO: $f"
done

Entradas de permiso redundantes (canal 4) — duplicados y concesiones específicas sombreadas por un comodín:

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

Cachés obsoletas más grandes (canal 8) — du -k en lugar de find -printf (solo GNU), para que funcione también en 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 con ruta de deshacer (capturar la fecha una vez para que el registro no pueda discrepar con el directorio):

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) movido skills/dead-skill -> _gc_trash/$gc_date/ (deshacer: mv de vuelta)" >> ~/.claude/gc_log.md

Eliminar una entrada de permiso confirmada como redundante (JSON no tiene comentarios — hacer copia de seguridad, registrar, luego editar):

cp ~/.claude/settings.local.json ~/.claude/settings.local.json.bak
echo "$(date -Iseconds) entrada de permiso eliminada: Bash(git push) (deshacer: restaurar desde .bak o volver a añadir)" >> ~/.claude/gc_log.md
jq '.permissions.allow -= ["Bash(git push)"]' ~/.claude/settings.local.json.bak \
  > ~/.claude/settings.local.json

Anti-patrones

• Aprobación masiva. Preguntar "¿eliminar los 15? [y/n]" contradice el diseño. Un elemento, una decisión.
• Borrado definitivo en la primera pasada. Si no hay copia en _gc_trash/ o renombrado a .disabled, lo hiciste mal.
• Tratar "antiguo" como "muerto". Una skill no utilizada durante 60 días puede ser estacional (temporada de impuestos, revisiones trimestrales). La antigüedad es una señal, no un veredicto — por eso un humano confirma.
• Limpiar la memoria truncando. Fusionar dos archivos de memoria contradictorios requiere leer ambos y conservar la verdad más nueva, no eliminar el más largo.
• Tocar cualquier cosa fuera de ~/.claude (o el .claude/ del proyecto). Config GC nunca se adentra en árboles de código fuente.

Buenas prácticas

• Ejecutar después de grandes adiciones, no solo en un calendario: instalar un paquete de 50 skills es exactamente el momento en que aparecen superposiciones con skills existentes.
• Cuando dos skills se superponen, preferir deshabilitar la que tenga la descripción de activación más débil — es la que probablemente nunca se disparaba de todos modos.
• La limpieza de permisos es el canal de mayor valor por minuto invertido: las entradas allow redundantes dificultan la revisión de seguridad.
• Conservar gc_log.md para siempre. Es pequeño, y "¿cuándo deshabilité ese hook y por qué?" surge más a menudo de lo que crees.

Habilidades relacionadas

• skill-stocktake — audita la calidad de las skills; config-gc audita la existencia de las skills. Ejecutar stocktake en lo que sobrevive a GC.
• workspace-surface-audit — la contraparte aditiva: recomienda qué instalar. config-gc es la mitad sustractiva del mismo ciclo de vida.
• configure-ecc — después de instalar skills con él, ejecutar config-gc para conciliar superposiciones con tu configuración preexistente.
• continuous-learning — produce los archivos de memoria que esta habilidad luego audita.
• security-review — se empareja bien con el canal de permisos.