Claude Code safe mode, 진짜 문제는 모델 밖에 있다

AI 코딩 에이전트를 쓰다 보면 이상한 순간이 온다.

어제는 잘 고치던 Claude Code가 오늘은 같은 저장소에서 엉뚱한 파일을 건드린다. 다른 프로젝트에서는 멀쩡한데, 특정 폴더에서만 이상한 명령을 반복한다.

이럴 때 제일 쉬운 결론은 “모델이 이상해졌다”다. 나도 처음엔 그렇게 생각하기 쉽다. 그런데 실제 삽질은 대부분 모델 안이 아니라 모델 바깥에서 생긴다.

CLAUDE.md, plugins, skills, hooks, MCP 서버, 작업 디렉터리. 이런 레이어가 하나씩 쌓이면 Claude Code는 더 편해진다. 동시에 어디서 결과가 바뀌었는지 찾기 어려워진다.

그래서 이번 Claude Code safe mode에서 내가 주목한 건 이름의 “safe”가 아니다. 핵심은 확장 레이어를 잠깐 걷어내고, 문제가 기본 상태에서도 재현되는지 확인하는 디버깅 습관이다.

safe mode는 보호막이 아니라 진단 도구다

Anthropic은 2026년 6월 8일 Claude Code v2.1.169 릴리스에서 --safe-mode와 CLAUDE_CODE_SAFE_MODE를 추가했다. Claude Code는 터미널에서 사용하는 AI 코딩 에이전트 CLI이고, CLI는 command-line interface, 즉 명령줄에서 실행하는 도구를 뜻한다.

릴리스 노트 기준으로 --safe-mode는 Claude Code를 시작할 때 customizations를 비활성화한다. 여기서 customizations는 사용자나 프로젝트가 덧붙인 설정과 확장 레이어다. 예를 들면 CLAUDE.md, plugins, skills, hooks, MCP servers가 여기에 들어간다.

claude --safe-mode

환경변수로도 같은 상태를 만든다. 환경변수는 셸이나 프로세스에 전달하는 실행 설정값이다.

CLAUDE_CODE_SAFE_MODE=1 claude

이 기능의 핵심은 “안전하게 격리 실행한다”가 아니다. 브라우저가 이상할 때 확장 프로그램을 끄고 실행하듯, Claude Code도 확장과 프로젝트 지시문을 끈 기본 상태에서 문제가 반복되는지 확인하는 흐름이다.

그래서 이름만 보고 safe mode를 보안 기능으로 홍보하면 위험하다. 파일 접근, 명령 실행, 권한 모델을 통제하려면 별도의 실행환경 설계와 조직 정책이 필요하다. --safe-mode는 그 역할을 대신하지 않는다.

모델이 아니라 실행환경이 결과를 바꾼다

AI 코딩 에이전트의 결과는 모델 하나로 결정되지 않는다. 같은 Claude를 쓰더라도 저장소마다 CLAUDE.md가 다르고, 연결된 MCP 서버가 다르고, 자동 실행되는 hook이 다르면 결과도 달라진다.

에이전트 결과 = 모델 + 프롬프트 + CLAUDE.md + plugins/skills + hooks + MCP + working directory + 조직 정책

여기서 working directory는 현재 명령이 실행되는 작업 디렉터리다. 에이전트는 이 위치를 기준으로 파일을 찾고, 명령을 실행하고, 프로젝트 지시문을 읽는다.

이 구조를 인정하면 디버깅 순서가 바뀐다. “왜 Claude가 갑자기 멍청해졌지?”가 아니라 “어떤 레이어가 개입했지?”를 묻게 된다. 이 질문이 실무에서는 시간을 줄인다. 모델 교체는 마지막 카드에 가깝고, 먼저 봐야 할 것은 재현 조건이다.

특정 프로젝트에서만 터지는 이유

특정 저장소에서만 이상한 결과가 나오면 대부분 “프로젝트별 상태”가 원인 후보에 오른다. Claude Code는 사용자가 보는 것보다 훨씬 많은 주변 정보를 먹고 움직인다.

오래된 CLAUDE.md는 잘못된 길잡이가 된다

CLAUDE.md는 Claude Code가 프로젝트에서 참고하는 지시문 파일이다. 팀 규칙, 빌드 방법, 테스트 명령, 코딩 스타일, 금지 사항을 적어두는 용도로 쓰인다.

문제는 이 파일이 오래되었을 때다. 예전에는 npm test를 썼지만 지금은 pnpm test로 바뀌었고, CLAUDE.md만 갱신되지 않았다고 하자. 에이전트는 최신 package.json보다 지시문을 더 강하게 따르며 잘못된 명령을 반복한다.

claude --safe-mode

safe mode에서는 정상인데 일반 실행에서만 실패한다면, CLAUDE.md가 첫 번째 의심 대상이다. 프롬프트를 더 길게 쓰기 전에 에이전트가 믿고 있는 문서부터 확인해야 한다.

plugins와 skills는 생산성과 디버깅 비용을 같이 만든다

plugin은 Claude Code에 기능을 추가하는 확장 모듈이고, skill은 반복 작업을 위해 묶어둔 지식과 절차다. 잘 쓰면 팀의 반복 작업을 줄인다. 하지만 문제가 생겼을 때는 원인 후보도 늘린다.

예를 들어 어떤 skill이 “테스트 전 항상 lint를 먼저 실행하라”고 유도한다. 어떤 plugin은 파일 탐색 방식이나 외부 도구 호출 방식을 바꾼다. 사용자는 “파일 하나만 고쳐줘”라고 요청했지만, 에이전트는 확장된 절차를 따라 움직인다.

v2.1.169에 disableBundledSkills 설정과 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 환경변수가 함께 추가된 것도 이 흐름에서 읽어야 한다. bundled skills는 Claude Code에 기본 포함된 skill 묶음이다. 기본 기능까지 포함해 무엇이 모델에게 보이는지 분리해서 봐야 하는 상황이 생긴 것이다.

CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1 claude

hooks는 조용히 결과를 다시 바꾼다

hook은 특정 시점에 자동 실행되는 스크립트다. 명령 실행 전후, 파일 수정 전후, 세션 시작 시점에 formatter나 검사 스크립트를 붙이는 방식이 대표적이다.

팀 자동화에는 편하다. 하지만 디버깅할 때는 함정이 된다. 에이전트가 파일을 수정했는데 formatter hook이 즉시 다시 바꿨을 가능성이 있다. 테스트 실패의 원인이 코드가 아니라 hook이 주입한 환경변수일 때도 있다.

이때 safe mode는 출발점이 된다. hooks가 꺼진 상태에서도 같은 증상이 나는지 비교하면, “Claude가 이상하다”는 느낌을 “자동화 레이어가 개입했다”는 재현 가능한 설명으로 바꾼다.

MCP는 외부 세계가 들어오는 통로다

MCP는 Model Context Protocol의 약자로, 에이전트가 외부 도구나 데이터 소스와 연결되도록 하는 규격이다. GitHub, 데이터베이스, 사내 문서, 이슈 트래커를 Claude Code에서 다루게 만드는 통로라고 보면 된다.

MCP가 많아질수록 실패 원인도 늘어난다. 서버가 죽었을 수 있고, 토큰 권한이 바뀌었을 수 있고, 조직 정책에서 허용되지 않는 서버일 수도 있다. Claude Code settings 문서에는 allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly 같은 managed MCP 관련 설정이 문서화돼 있다.

v2.1.169의 enterprise managed MCP policy enforcement 수정도 이 맥락에서 눈여겨봐야 한다. enterprise managed MCP policy는 조직이 허용한 MCP 서버와 정책을 강제하는 관리 기능이다. 릴리스 노트는 reconnect, IDE에서 온 config, 설치 후 첫 세션의 --mcp-config, remote settings 로드 전 시점 등 일부 상황에서 enforcement가 제대로 적용되지 않던 문제를 고쳤다고 설명한다.

다만 이 수정이 모든 기업 환경의 MCP 리스크를 없앤다는 뜻은 아니다. 공식 릴리스에 적힌 특정 enforcement 버그가 고쳐졌다고 해석하는 편이 안전하다.

Claude Code가 이상할 때의 확인 순서

문제를 빨리 줄이려면 같은 요청, 같은 저장소, 같은 브랜치에서 하나씩 조건을 바꿔야 한다. 느낌으로 원인을 찍기 시작하면 모델, 프롬프트, 도구 설정이 한꺼번에 섞인다.

1. safe mode에서 먼저 재현한다

가장 먼저 확장을 끈 기본 상태를 만든다.

claude --safe-mode

스크립트나 CI 환경에서는 환경변수 방식이 편하다. CI는 continuous integration, 즉 코드 변경 뒤 빌드와 테스트를 자동으로 돌리는 환경을 뜻한다.

CLAUDE_CODE_SAFE_MODE=1 claude

safe mode에서도 실패한다면 모델, 기본 CLI, 요청 자체, 프로젝트 파일, 의존성 문제를 본다. safe mode에서는 정상인데 일반 실행에서만 실패한다면 customizations 레이어가 유력하다.

2. 프로젝트 지시문을 현재 상태와 맞춘다

CLAUDE.md에는 오래된 명령이 남기 쉽다. 테스트 명령, 빌드 명령, 패키지 매니저, 배포 경로처럼 자주 바뀌는 항목을 먼저 본다.

# 예시: 프로젝트 지시문에서 오래된 test/build 명령을 검색
rg "npm test|yarn test|pnpm test|pytest|make test" CLAUDE.md

여기서 rg는 ripgrep이라는 빠른 텍스트 검색 도구다. 명령어 자체보다 중요한 것은 에이전트가 따르는 문서가 현재 프로젝트와 맞는지 확인하는 습관이다.

3. 확장은 한꺼번에 켜지 말고 층별로 되돌린다

safe mode에서 정상이라면 모든 확장을 한 번에 다시 켜면 안 된다. custom plugin, custom skill, bundled skill, hook, MCP를 분리해서 비교해야 한다.

좋은 디버깅은 빠른 결론이 아니라 비교 가능한 실행에서 나온다. 같은 요청을 두고 조건 하나만 바꿔야 원인이 보인다. 여러 설정을 동시에 바꾸면 문제가 사라져도 무엇이 원인이었는지 모른다.

4. hooks와 MCP 로그를 남긴다

파일이 예상과 다르게 바뀌면 hooks를 본다. 외부 도구 호출에서만 실패하면 MCP를 본다. 서버 연결 상태, 권한, allowlist와 denylist를 함께 확인해야 한다.

{
  "allowedMcpServers": ["github", "internal-docs"],
  "deniedMcpServers": ["unknown-local-server"],
  "allowManagedMcpServersOnly": true
}

위 JSON은 운영 관점을 설명하기 위한 예시다. 실제 키의 적용 위치와 범위는 Claude Code 공식 settings 문서를 기준으로 맞춰야 한다.

5. /cd 이후의 위치를 기록한다

v2.1.169에는 세션 중 작업 디렉터리를 바꾸는 /cd 명령도 추가됐다. 이 기능은 편하지만, 현재 위치가 바뀌면 적용되는 프로젝트 지시문과 실행 명령도 함께 달라진다.

1. 시작 디렉터리
2. /cd로 이동한 디렉터리
3. 각 위치의 CLAUDE.md 존재 여부
4. 실행한 명령
5. safe mode 재현 여부

“Claude가 이상했음”은 버그 리포트가 아니다. “safe mode에서는 정상, 일반 실행에서는 특정 CLAUDE.md가 있는 디렉터리에서만 실패”는 팀원이 다시 확인할 수 있는 기록이다.

팀 운영에서는 권한보다 재현성이 먼저다

개인 개발자는 MCP 서버를 쉽게 붙이고, hooks를 만들고, skills를 추가한다. 생산성은 올라간다. 동시에 팀 입장에서는 누가 어떤 확장을 어떤 권한으로 쓰는지 관리해야 하는 문제가 생긴다.

특히 MCP는 외부 도구와 연결되는 통로라서 allowlist와 denylist가 필요하다. 모든 팀원이 각자 다른 MCP 서버를 붙인 상태에서 같은 문제를 보고하면 재현이 어렵다. 누군가는 GitHub MCP를 쓰고, 누군가는 사내 문서 MCP를 쓰고, 누군가는 로컬 실험 서버를 붙인 상태라면 결과가 달라지는 게 자연스럽다.

팀 단위로는 최소한 아래 항목을 정해야 한다.

- 팀 표준 CLAUDE.md 위치와 관리 방식
- 허용하는 MCP 서버 목록
- 금지하거나 검토가 필요한 MCP 서버 목록
- hooks 도입 전 리뷰 기준
- custom skills/plugins 변경 기록
- 문제가 생겼을 때 safe mode 재현 로그를 남기는 방식

에이전트 권한은 편리한 기능이면서 운영 책임이다. 이 책임을 문서화하지 않으면, 모델 문제가 아닌데도 모델을 바꾸는 삽질을 반복하게 된다.

결론: 좋은 에이전트 운영은 원인을 끄집어내는 습관에서 시작한다

Claude Code v2.1.169의 --safe-mode는 작은 옵션처럼 보인다. 하지만 AI 코딩 에이전트를 팀 도구로 오래 쓰려면 꽤 상징적인 변화다.

에이전트는 이제 모델과 프롬프트만으로 설명되지 않는다. 프로젝트 지시문, plugins, skills, hooks, MCP 서버, 작업 디렉터리, 조직 정책이 함께 결과를 만든다. 그래서 실무에서 덜 헤매려면 질문을 바꿔야 한다.

프롬프트를 어떻게 더 고칠까?

그 전에 먼저 물어야 한다.

확장 끄고도 재현될까?

이 질문 하나가 모델 탓과 환경 문제를 갈라준다. Claude Code safe mode의 가치는 바로 여기에 있다. 보안 sandbox가 아니라, 실패를 재현 가능한 문제로 바꾸는 첫 번째 스위치다.

참고자료

• Anthropic Claude Code Release v2.1.169 — --safe-mode, /cd, bundled skills 관련 릴리스 노트
• Anthropic Claude Code CHANGELOG — Claude Code 변경 이력 원문
• Claude Code Settings 문서 — settings와 managed MCP 관련 설정 참고
• Claude Code MCP 문서 — MCP 연결 방식 참고
• Claude Code GitHub README — Claude Code 공식 저장소