config-gc

Config GC — Claude Code 구성을 위한 가비지 컬렉션

런타임 가비지 컬렉션에서 차용한 개념입니다. 더 이상 참조되지 않거나, 중복되거나, 만료되었거나, 가치가 낮은 객체를 주기적으로 스캔하고 공간을 회수합니다. 중요한 차이점: 여기서는 수집에 사람이 직접 관여해야 합니다. 절대 자동으로 삭제하지 마세요.

활성화 시점

• 사용자가 Claude Code 구성을 정리하거나, 감사하거나, 간소화해 달라고 요청할 때
• 사용자가 스킬이 너무 많거나, 훅이 시끄럽거나, 세션 시작이 느리다고 불평할 때
• 월간/주기적 구성 검토가 예정된 경우
• 대규모 스킬 팩(예: 이 저장소)을 설치한 후, 기존 설정과의 중복을 확인해야 할 때

다음의 경우에는 활성화하지 마세요: 프로젝트 소스 코드 정리(리팩터링), 채팅 기록 지우기, Claude Code 자체 제거.

설계 철학

1. 추가 전용 구성은 누수됩니다. 스킬, 메모리 파일, 훅, 권한 항목은 계속해서 추가만 됩니다. 주기적인 검토 없이는 조용히 썩어갑니다.
2. 일회성 대규모 삭제보다 정기적인 감사가 낫습니다. 약 30일마다 스캔하고, 매번 소량의 후보를 제안합니다.
3. 채널별 전략. 각 누적 유형(스킬, 훅, 권한 등)은 고유한 부실 신호를 가집니다. 모든 곳에 동일한 규칙을 적용하지 마세요.
4. 먼저 소프트 삭제. .disabled로 이름 변경 > ~/.claude/_gc_trash/로 이동 > 실제 삭제 순서로 진행합니다. 항상 복구 경로를 남겨두세요.
5. 반드시 사람이 최종 확인. 각 후보마다 [y/n/skip] 확인을 받습니다. "전체 동의" 단축키는 없습니다.
6. 로그를 남깁니다. 모든 GC 실행은 ~/.claude/gc_log.md에 추가됩니다: 무엇을, 왜, 어떻게 취소할 수 있는지 기록합니다.

스캔 채널

#	채널	경로	부실/중복 신호
1	스킬	~/.claude/skills/*/	이름이 심하게 중복됨; 최근 대화 기록에서 한 번도 트리거되지 않음; 사용자의 실제 작업과 도메인이 일치하지 않음; SKILL.md가 깨졌거나 비어 있음
2	메모리	~/.claude/**/memory/*.md + 인덱스	한 주제에 여러 인덱스 항목; 내용이 최신 항목과 모순됨; 날짜가 지난 항목; 인덱스에서 누락된 고아 파일; 병합해야 할 100단어 미만 조각
3	훅	~/.claude/hooks/ + 설정	디스크에 존재하지만 어떤 훅 설정에도 참조되지 않는 스크립트; 재작성으로 대체된 구버전
4	권한	settings.json / settings.local.json의 permissions.allow	중복 항목; 와일드카드(예: Bash(*)가 허용된 경우 Bash(git push))로 이미 커버되는 특정 항목; 과거 실험에서 남은 일회성 부여
5	MCP 서버	~/.claude.json 또는 프로젝트 .mcp.json	연결에 실패하는 서버; 기능적으로 중복되는 서버; 오랫동안 사용되지 않은 서버
6	예약된 알림/작업	사용자가 보관하는 모든 위치	30일 이상 지난 일회성 작업; 대상 스크립트가 더 이상 존재하지 않는 작업
7	프로젝트 기록	~/.claude/projects/*/	오래된 핸드오프 스냅샷; 새 상태로 대체된 세션 기록
8	런타임 캐시	cache/, file-history/, logs/, shell-snapshots/	크기와 수정 시간 기준 정렬; 30일 이상 오래되고 큰 항목 제안

워크플로우

1. 스캔 모든 채널(또는 사용자가 지정한 하위 집합). 경로, 채널, 신호 플래그, 크기, 최종 수정 시간과 함께 후보를 수집합니다.
2. 순위 지정 신뢰도에 따라 (깨지거나 고아인 경우 = 높음; 단순히 오래된 경우 = 낮음) 후보를 번호가 매겨진 표로 제시합니다. 실행당 최대 약 20개 후보로 제한합니다. GC는 주기적이지, 완전하지 않습니다.
3. 하나씩 확인. 각 후보에 대해 증거를 보여주고 [y/n/skip]을 묻습니다. 사용자는 언제든지 중단할 수 있습니다.
4. 확인된 항목 소프트 삭제: 스킬/훅은 .disabled 이름 변경을, 파일은 _gc_trash/<날짜>/ 이동을 선호합니다. 권한 항목은 JSON에 존재하므로(주석 불가능): 설정 파일을 백업하고, 제거된 각 항목을 gc_log.md에 그대로 기록한 후 jq로 allow 배열에서 제거합니다. 사용자가 명시적으로 요청할 때만 하드 삭제를 수행합니다.
5. 로그 기록 ~/.claude/gc_log.md에: 타임스탬프, 처리된 항목, 복구 지침.
6. 보고: 회수된 크기, 여전히 정상인 채널, 권장되는 다음 검토 날짜.

예제 스캔 명령어

고아 훅 스크립트(채널 3) — 디스크에 있지만 어떤 훅 설정에도 참조되지 않는 스크립트:

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

중복 권한 항목(채널 4) — 중복 및 와일드카드로 인해 가려진 특정 권한:

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

가장 큰 오래된 캐시(채널 8) — GNU 전용 find -printf 대신 du -k를 사용하여 macOS/BSD에서도 작동:

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

복구 경로를 포함한 소프트 삭제(날짜를 한 번 캡처하여 로그와 디렉토리가 불일치하지 않도록):

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

확인된 중복 권한 항목 제거(JSON은 주석을 허용하지 않음 — 백업, 기록, 편집 순):

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

안티 패턴

• 일괄 승인. "15개 모두 삭제할까요? [y/n]"라고 묻는 것은 설계를 무너뜨립니다. 하나의 항목, 하나의 결정입니다.
• 첫 번째 패스에서 하드 삭제. _gc_trash/ 복사본이나 .disabled 이름 변경이 없다면 잘못된 것입니다.
• "오래된" 것을 "죽은" 것으로 간주. 60일 동안 손대지 않은 스킬이 계절성(세금 시즌, 분기별 검토)일 수 있습니다. 나이는 신호일 뿐, 확정은 아닙니다. 그래서 사람이 확인하는 것입니다.
• 메모리를 자르기만 하여 정리. 두 개의 상충하는 메모리 파일을 병합하려면 두 파일을 모두 읽고 더 최신 정보를 유지해야 하며, 더 긴 파일을 삭제하는 것이 아닙니다.
• ~/.claude 외부의 항목 건드리기(또는 프로젝트의 .claude/). Config GC는 소스 트리로 절대 넘어가지 않습니다.

모범 사례

• 대규모 추가 후 실행하십시오. 달력 기준뿐만 아니라: 50개 스킬 팩을 설치하는 것은 기존 스킬과의 중복이 나타나는 정확한 시점입니다.
• 두 스킬이 겹칠 때는 트리거 설명이 약한 쪽을 비활성화하는 것을 선호하십시오. 아마도 어차피 트리거되지 않았을 스킬입니다.
• 권한 정리는 분당 소요 시간 대비 가장 가치가 높은 채널입니다. 중복 허용 항목은 보안 검토를 더 어렵게 만듭니다.
• gc_log.md를 영원히 보관하십시오. 크기가 작고, "그 훅을 언제 비활성화했고 왜 그랬지?"라는 질문이 생각보다 자주 발생합니다.

관련 스킬

• skill-stocktake — 스킬 품질을 감사합니다; config-gc는 스킬 존재를 감사합니다. GC에서 살아남은 스킬에 대해 stocktake를 실행하십시오.
• workspace-surface-audit — 추가적인 대응 도구입니다: 설치할 항목을 추천합니다. config-gc는 동일한 수명 주기의 제거적인 절반입니다.
• configure-ecc — 이 스킬로 스킬을 설치한 후, config-gc를 실행하여 기존 설정과의 중복을 해소하십시오.
• continuous-learning — 이 스킬이 나중에 감사할 메모리 파일을 생성합니다.
• security-review — 권한 채널과 잘 어울립니다.