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 — 권한 채널과 잘 어울립니다.