Claude Code가 갑자기 이상하게 동작할 때가 있습니다. 예전에는 잘 되던 명령이 실패하거나, 특정 MCP 서버가 응답을 지연시키거나, 프로젝트 CLAUDE.md의 지시가 예상보다 강하게 먹히거나, hook과 plugin이 서로 간섭할 수 있습니다.
이럴 때 바로 쓸 수 있는 기능이 --safe-mode ↗입니다. Claude Code v2.1.169에 추가된 safe mode는 커스텀 설정을 끈 깨끗한 상태로 세션을 시작해, 문제가 Claude Code 자체인지 주변 설정인지 빠르게 가르게 해줍니다.
이 글은 작성 시점 2026-06-17 · Claude Code Week 24 문서 ↗ 스냅숏 기준으로 정리했습니다.
무엇을 끄는가
공식 문서에 따르면 safe mode에서는 다음 항목이 로드되지 않습니다.
| 비활성화되는 것 | 예시 |
|---|---|
| 프로젝트 지침 | CLAUDE.md |
| skills | 번들/커스텀 skill |
| plugins | marketplace plugin, 로컬 plugin |
| hooks | SessionStart, Stop, MessageDisplay 등 |
| MCP servers | 외부 도구 서버 |
| custom commands/agents | 프로젝트별 slash command, custom agent |
반대로 인증, 모델 선택, built-in tools, permission model은 계속 동작합니다. 그래서 “Claude Code가 아예 망가졌나?”와 “내 설정 중 하나가 문제인가?”를 분리하기 좋습니다.
사용법
터미널에서 이렇게 시작합니다.
claude --safe-mode환경 변수로도 켤 수 있습니다.
CLAUDE_CODE_SAFE_MODE=1 claude문제가 safe mode에서 사라지면 원인은 대체로 프로젝트 설정, plugin, hook, MCP 서버, custom command/agent 중 하나입니다. 이때는 하나씩 다시 켜며 좁혀가면 됩니다.
flowchart TD
A[일반 세션에서 문제 발생] --> B[claude --safe-mode 실행]
B --> C{문제가 재현되는가}
C -->|예| D[Claude Code 버전·권한·모델·네트워크 확인]
C -->|아니오| E[커스텀 설정 중 원인 존재]
E --> F[CLAUDE.md]
E --> G[plugins / skills]
E --> H[hooks]
E --> I[MCP servers]언제 쓰면 좋은가
safe mode는 특히 다음 상황에서 유용합니다.
- 새 plugin을 설치한 뒤 응답이 이상해졌을 때
- MCP 서버가 느리거나 실패하는지 의심될 때
- hook이 메시지를 바꾸거나 작업을 막는지 확인할 때
- 프로젝트
CLAUDE.md지시가 과하게 작동하는지 볼 때 - custom command나 skill이 예상 밖 도구 제한을 걸었을 때
블로그 대표 이미지 콘셉트
Claude Code 터미널이 두 화면으로 나뉜 일러스트가 좋습니다. 왼쪽은 plugins, hooks, MCP, skills, CLAUDE.md가 복잡하게 얽혀 에러 표시가 뜬 일반 세션이고, 오른쪽은 claude --safe-mode로 모든 확장 요소가 꺼진 깨끗한 터미널입니다.
중앙에는 “Isolate the problem”이라는 문구와 함께 원인을 하나씩 다시 켜는 체크리스트가 배치됩니다.
마무리
--safe-mode는 화려한 기능은 아니지만, Claude Code를 오래 쓰는 사람에게는 매우 실용적입니다. 에이전트 환경은 설정과 확장이 늘어날수록 강력해지지만, 그만큼 문제 원인도 넓어집니다.
Claude Code가 이상하면 바로 고치려 들기보다 먼저 깨끗한 세션에서 재현해보세요. 사라지는 문제라면 원인은 대개 내가 붙인 확장 지점 안에 있습니다.