[Claude Code] 뭐가 망가뜨렸는지 안전 모드로 찾아요

[Claude Code] 뭐가 망가뜨렸는지 안전 모드로 찾아요

Claude Code가 갑자기 이상해질 때가 있어요. 6월 둘째 주(v2.1.169) 업데이트로 들어온 --safe-mode는 내가 붙여둔 설정을 전부 끈 상태로 Claude Code를 켜는 옵션이에요. Anthropic 공식 문서 기준으로 설정 문제를 격리하는 용도예요.

01. 한 줄로 모든 커스터마이징을 끄고 시작해요

실행 방법은 평소 명령에 옵션 하나만 붙이면 돼요.

claude --safe-mode

이렇게 켜면 그 세션에서는 직접 붙여둔 설정이 하나도 로드되지 않아요. 평소 환경 그대로 두고, 이 명령으로 켠 세션에서만 깨끗한 상태로 돌아간다고 공식 문서에는 나와 있어요.

02. 끄는 것과 그대로 두는 것이 나뉘어요

안전 모드에서 로드되지 않는 건 CLAUDE.md, 스킬, 플러그인, hook, MCP 서버, 그리고 직접 만든 커스텀 커맨드·에이전트예요. 평소에 손으로 붙여둔 것들이 전부 빠지는 셈이에요.

반대로 로그인 인증, 모델 선택, 내장 도구, 권한(permissions)은 그대로 동작한다고 해요. 그래서 안전 모드라고 해서 아무것도 못 하는 건 아니고, 기본 기능은 쓰면서 내가 추가한 설정만 빼고 비교할 수 있어요.

한 가지 단서가 있어요. 회사가 조직 차원에서 배포한 managed 설정(정책 hook·상태줄)은 안전 모드에서도 일부 적용된다고 공식 문서에 나와 있어요. 그래서 회사 환경이라면 안전 모드에서도 안 꺼지는 게 있을 수 있어요.

03. 문제가 사라지면 그중 하나가 원인이에요

쓰는 방식은 단순해요. 평소 세션에서 이상하던 증상이 --safe-mode로 켰을 때 사라지면, 위에서 빠진 설정 중 하나가 원인이라는 신호예요.

거기서부터 플러그인이나 MCP 서버를 하나씩 다시 켜보며 범위를 좁히면 돼요. 설정을 많이 붙여 쓸수록 "뭐가 망가뜨렸는지" 찾기가 어려운데, 그 출발점을 한 줄로 만들어주는 옵션이에요.

04. 환경 변수로도 켤 수 있어요

옵션 대신 CLAUDE_CODE_SAFE_MODE 환경 변수를 설정해도 같은 효과라고 공식 문서에 나와 있어요. CI나 스크립트처럼 매번 옵션을 붙이기 번거로운 곳에서 쓰기 편한 방식이에요.

플러그인·MCP·hook을 많이 붙여 쓰는 사람일수록 설정 충돌을 만날 일이 많은데, 그럴 때 깨끗한 기준선을 빠르게 세울 수 있다는 게 실용적으로 중요한 부분이에요. 실제 진단이 얼마나 빨라지는지는 직접 써보고 판단할 부분이에요.

출처: Claude Code — What's new (Week 24), Debug your config

이 글은 공식 발표 내용을 정리한 것이고, Anthropic으로부터 어떤 형식의 협찬도 받지 않았습니다.