[Claude Code 스킬] --safe-mode — 커스터마이징을 전부 끄고 고장 원인을 절반으로 가르는 대조군 실행 | DAKER 커뮤니티
무엇
--safe-mode는 내가 얹어 둔 설정을 전부 끈 채로 Claude Code를 딱 한 세션만 실행하는 플래그다. CLAUDE.md, 스킬, 커스텀 슬래시 커맨드, 플러그인, 훅, MCP 서버, 커스텀 서브에이전트가 모두 로드되지 않는다. 대신 로그인 · 모델 선택 · 내장 도구 · 권한 규칙은 평소대로 동작하므로 작업 자체는 계속할 수 있다.
실험으로 치면 대조군(control)이다. 약이 듣는지 보려면 약을 뺀 집단이 필요하듯, 내 설정이 범인인지 보려면 설정을 뺀 세션이 필요하다. v2.1.169에서 추가됐고, 설정 파일을 지우거나 옮기지 않으므로 세션을 닫으면 원래대로 돌아온다.
언제 쓰나
CPU · 메모리가 갑자기 치솟거나, 응답이 눈에 띄게 느려질 때
훅이 엉뚱하게 발동하거나 파일 편집이 막힐 때
어제까지 되던 일이 플러그인 · MCP 서버를 하나 추가한 뒤부터 안 될 때
/doctor는 "이상 없음"이라는데 증상은 그대로일 때CI · 스크립트에서 같은 증상이 재현되는지 확인할 때(환경변수 형태로)
사용법
# 이번 세션만 커스터마이징을 전부 끄고 실행
claude --safe-mode
# 환경변수도 같은 효과 (스크립트 · CI에서 유용)
CLAUDE_CODE_SAFE_MODE=1 claude실행하기 전에, 무엇이 실제로 로드됐는지 눈으로 확인해 두면 비교가 쉬워진다.
/doctor # 설치 · 설정 · 확장 · 컨텍스트 자동 점검
/hooks # 이번 세션에 등록된 훅을 이벤트별로 나열
/mcp # MCP 서버 연결 상태
/context # 컨텍스트를 무엇이 얼마나 차지하는지판정 규칙은 단순하다. 안전 모드에서 증상이 사라지면 원인은 내 설정 안에 있다. 그대로 남으면 설정 밖, 즉 Claude Code 자체의 문제이거나 모델 행동의 문제다.
설정 밖으로 판정됐는데도 확신이 서지 않으면, 사용자 설정과 프로젝트 설정까지 통째로 우회하는 더 강한 대조군을 만든다.
# 안전 모드에서도 증상이 남는다면 : 더 강한 대조군
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
# ~/.claude 전체를 우회하고,
# .claude / .mcp.json / CLAUDE.md 가 없는 폴더에서 실행한다
팁
1. 하나씩 말고 절반씩 되켠다. 안전 모드에서 정상이라면 범인은 내 설정 어딘가에 있다. 후보가 8개일 때 하나씩 끄면 평균 4번을 시도해야 하지만, 절반으로 갈라 가면 3번이면 끝난다(log2 8 = 3). 플러그인 → MCP → 훅 → 스킬 → CLAUDE.md 순으로 덩어리를 나눠 켜 보자.
2. 안전 모드는 격리이지 삭제가 아니다. 파일은 그대로 남는다. 그래서 "일단 다 지워 보고 다시 깔기"보다 훨씬 되돌리기 쉽고, 원인을 찾은 뒤에도 나머지 설정을 잃지 않는다.
3. 훅이 목록에 안 보이면 애초에 읽히지 않은 것이다. /hooks에 내가 정의한 훅이 나타나지 않는다면 위치가 잘못됐을 가능성이 크다. 훅은 설정 파일 안의 hooks 키에 들어가야 하며, 별도 파일로 두면 로드되지 않는다.
4. 메모리가 계속 높다면 /heapdump로 스냅샷을 남긴다. 다만 .heapsnapshot에는 프로세스의 모든 문자열이 담기므로 공개 이슈에 첨부하지 말고, 통계만 들어 있는 -diagnostics.json만 올린다.