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이 예상 밖 도구 제한을 걸었을 때
마무리
에이전트 환경은 설정과 확장이 늘어날수록 할 수 있는 일이 많아지고, 문제 원인의 범위도 넓어집니다. --safe-mode는 그 범위를 줄여 줍니다.
Claude Code가 이상하면 바로 고치지 말고 먼저 safe mode 세션에서 재현해 보세요. safe mode에서 사라지는 문제라면 원인은 대개 사용자가 추가한 확장 지점에 있습니다.