Claude Code 복구: 안전 모드, /cd, 대체 모델
Markdown안전 모드, /cd 명령, 대체 모델, 설정 복구를 활용한 Claude Code 진단. 점검 순서와 원래의 제한 사항을 설명합니다.
전체 글 읽기
에이전트 작업에 관한 실용 자료: Ailoot 문서.
2026년 6월 Claude Code에는 어떤 변화가 있었나요?
핵심 요점
2026년 6월 8일, Claude Code v2.1.169에서 Anthropic은 --safe-mode 플래그와 /cd 명령을 추가했습니다. 이틀 전인 6월 6일에는 v2.1.166에서 최대 3개 모델을 연결하는 대체 모델 기능이 도입됐습니다. 이 세 기능은 바이브 코더가 가장 흔히 겪는 문제, 즉 “모든 게 망가졌는데 누구 탓인지 모르겠고, 재설치하느라 한 시간을 날리고 싶지 않다”는 상황을 해결합니다.
이전에는 Claude Code가 이상하게 동작하기 시작하면—끝없이 도는 로딩 표시, 시작 중 충돌, CLAUDE.md 규칙을 무시하는 에이전트, 아무런 신호 없이 실행되지 않는 hook—빠져나올 방법은 하나뿐이었습니다. .claude/settings.json의 일부를 직접 주석 처리하거나, MCP 서버를 하나씩 비활성화하거나, 최악의 경우 ~/.claude를 삭제하고 다시 설치하는 것이었습니다. 설명된 한 사례에서는 ~/.claude를 삭제해 한 시간 반 동안 구축한 MCP 서버 설정을 잃었습니다. 나중에야 원인이 CLAUDE.md의 한 줄이라는 사실이 드러났습니다. 10초면 찾을 수 있었지만, 전체 복구를 마친 뒤에야 알게 됐습니다.
2026년 6월 Anthropic은 이 상황을 바꾸는 세 가지 메커니즘을 출시했습니다. 무엇이 언제 추가됐는지 간단히 살펴보겠습니다.
| 버전 | 날짜 | 추가된 기능 |
|---|---|---|
| 2.1.166 | 2026년 6월 6일 | fallbackModel 설정 + 대화형 세션용 --fallback-model 플래그 |
| 2.1.169 | 2026년 6월 8일 | --safe-mode 플래그와 CLAUDE_CODE_SAFE_MODE 환경 변수, /cd 명령 |
| 2.1.176 | 2026년 6월 12일 | 수정 사항: /cd와 worktree 전환 후에도 이전 git 브랜치가 표시되던 문제 해결 |
아래에서는 각 메커니즘을 단계별로 설명하고, Claude Code 세션이 잘못되기 시작할 때 적용할 순서도 함께 살펴봅니다.
Claude Code에서 가장 흔히 문제가 생기는 원인은 무엇인가요?
핵심 요점
설명된 경험을 보면, 바이브 코더가 Claude Code에서 문제를 겪는 가장 흔한 원인은 네 가지입니다. 서로 모순되는 규칙이 담긴 지나치게 긴 CLAUDE.md, 잘못된 종료 코드를 반환하는 hook, 오류를 알리지 않고 실패하는 MCP 서버, 세 수준의 settings.json에 겹쳐 설정된 항목입니다. 원인은 하나이고 진단에는 몇 분이면 되지만, 당황한 나머지 곧바로 rm -rf를 실행하기 쉽습니다.
설명된 사례에서는 처음에 CLAUDE.md를 80줄로 작성했고, 한 달 동안은 잘 작동했습니다. 두 번째 달부터는 Claude가 일주일에 한 번 설정된 규칙을 모두 어기는 일이 눈에 띄기 시작했습니다. .env를 건드리고, git push --force를 실행하고, node_modules를 뒤졌습니다. 악의적인 행동이 아니라 단순히 잊어버린 것이었습니다. 한 번은 .gitignore가 삭제됐는데, 이유를 바로 알아내지 못했습니다. 이 상황은 CLAUDE.md 가이드에서 더 자세히 다룹니다.
CLAUDE.md가 400줄을 넘으면 문제가 조용히 생기기 시작합니다. 세션 시작 시 컨텍스트 창의 상당 부분을 차지하고 중요한 지침을 부차적인 지침 사이에 묻히게 합니다. Claude는 여전히 파일을 형식상 읽으므로, 겉으로는 “규칙이 있는데도 작동하지 않는다”처럼 보입니다. 지나치게 커진 계약에서 흔히 나타나는 징후입니다.
두 번째로 흔한 원인은 hook입니다. Claude Code hooks에는 Anthropic이 강조하지 않는 특성이 있습니다.
즉, Python hook의 sys.exit(1)이나 Unix 관례상 “오류로 실패”를 뜻하는 코드는 Claude를 멈추지 않습니다. 코드 2만 차단 기능을 합니다. 설명된 사례에서는 hook을 “강제 금지”로 여겼지만, 실제로는 불만을 로그에 남기면서 작업을 허용했습니다.
세 번째 계층은 MCP 서버이며, 이 역시 나름의 방식으로 문제를 일으킵니다.
증상은 대개 같습니다. MCP 명령은 사용할 수 있지만 traceback 없이 failed를 반환합니다. MCP 설정과 claude mcp add로 서버를 추가하는 방법은 별도 가이드를 참조하세요.
네 번째 원인은 3단계 settings.json 계층 구조입니다. ~/.claude/settings.json(사용자 수준), 프로젝트 루트의 .claude/settings.json(프로젝트 수준), .claude/settings.local.json(로컬 수준), 그리고 기업 관리자가 배포한 관리형 설정이 추가로 있을 수 있습니다. 이 설정들은 우선순위 규칙에 따라 결합됩니다. 프로젝트 수준에서 누군가 MCP 서버를 추가했는데 사용자 수준에 실행 설정이 다른 유사한 항목이 있으면, 조용한 충돌이 발생해 “Claude Code가 고장 났다”는 인상을 줍니다.
--safe-mode는 어떻게 작동하고 무엇을 비활성화하나요?
핵심 요점
claude --safe-mode는 사용자 지정 항목을 완전히 비활성화한 상태로 Claude Code를 실행합니다. 비활성화 대상은 CLAUDE.md, 플러그인, skill, hook, MCP 서버, 사용자 명령, 에이전트, 출력 스타일, workflow, 키 바인딩입니다. 인증, 모델 선택, 기본 제공 도구, 권한은 그대로 유지됩니다. 진단 도구로 사용할 수 있습니다. 안전 모드에서 문제가 사라지면 추가한 계층 중 하나가 원인입니다.
v2.1.169 변경 로그에 실린 Anthropic의 원문은 다음과 같습니다.
진단 목적으로 사용자 지정 항목(
CLAUDE.md, 플러그인, skill, hook, MCP 서버)을 비활성화한 상태로 Claude Code를 실행하는--safe-mode플래그(및CLAUDE_CODE_SAFE_MODE)를 추가했습니다.
Anthropic은 모델 설정 문서에서 다음과 같이 설명합니다.
사용자 지정 항목이 원인인지 확인하려면
claude --safe-mode로 세션을 시작하세요. 이 명령은CLAUDE.md, skill, MCP 서버, hook을 비활성화합니다. Git 상태와 디렉터리 이름은 사용자 지정 항목으로 간주되지 않으므로 계속 사용할 수 있습니다.
이는 진단 도구이지 “깨끗한 환경”이 아닙니다. 안전 모드는 한 가지 질문에 답하도록 돕습니다. 문제의 원인이 Claude Code의 기본 동작인가요, 아니면 추가한 사용자 지정 항목인가요? 이는 컨텍스트 엔지니어링의 일부로, 주어진 순간에 Claude가 무엇을 보고 무엇을 보지 않을지 관리하는 방법입니다. 안전 모드에서 모두 작동한다면 이분 탐색으로 각 계층을 점검하면 됩니다. 작동하지 않는다면 설치, 인증, 네트워크 또는 인프라가 문제이므로 claude doctor와 로그를 살펴보는 것이 좋습니다.
안전 모드에서 비활성화되는 항목(Anthropic 공식 목록의 주요 계층 5개):
- 모든 수준의
CLAUDE.md(사용자 / 프로젝트) - 플러그인
- Skill
- Hook
- MCP 서버
계속 작동하는 항목:
- 인증(OAuth 세션 또는 API 키)
- 모델 선택(
--model sonnet,--model opus) - 기본 제공 도구(Read, Write, Bash, Grep 등)
- 권한
- Git 상태
- 디렉터리 이름
중요한 세부 사항이 하나 있습니다. 안전 모드는 기업 관리자가 설정한 관리형/정책 설정을 비활성화하지 않습니다. Bedrock GovCloud 또는 MDM 설정에서 availableModels를 지정하는 팀에서 일한다면 해당 제한은 계속 적용됩니다. 안전 모드는 사용자 지정 항목만 비활성화하며 기업 정책은 그대로 유지합니다.
계층을 분리해 60초 안에 원인을 찾으려면 어떻게 해야 하나요?
핵심 요점
1단계: 문제가 발생했던 동일한 폴더에서 claude --safe-mode를 실행합니다. 작동하면 사용자 지정 항목이 문제이므로 하나씩 다시 활성화합니다. 순서는 CLAUDE.md -> hook -> MCP -> skill입니다. 안전 모드에서도 작동하지 않으면 인증, 버전, 네트워크 또는 OS가 문제입니다. 이 경우 rm -rf를 건드리지 말고 claude doctor를 실행해 자동 진단을 받으세요.
Claude Code가 “더는 말을 듣지 않는” 경우를 위한 진단 절차입니다. 아래 명령을 실행하려면 최소 Claude Code v2.1.169가 필요합니다. 이전 버전이라면 먼저 업데이트하세요(npm update -g @anthropic-ai/claude-code 또는 Anthropic의 기본 설치 프로그램 사용).
- 문제가 발생했던 동일한 폴더를 엽니다.
claude --safe-mode를 실행합니다.- 정상적으로 시작되면 원래 요청을 확인합니다. 작동했나요? 그렇다면 계층 중 하나가 원인입니다. 4단계로 이동합니다.
- 안전 모드에서도 문제가 계속되면 설정을 건드리지 마세요. 먼저
claude doctor를 실행해 인증, 버전, 설치 충돌을 확인합니다.
안전 모드가 정상적으로 시작되면 가장 의심되는 항목부터 한 번에 하나씩 계층을 다시 활성화합니다. 설명된 경험을 바탕으로 한 순서는 다음과 같습니다.
CLAUDE.md. 안전 모드 없이claude를 실행하되, 파일 이름을 임시로 바꿉니다:mv CLAUDE.md CLAUDE.md.bak. 문제가 해결되면 해당 파일이 원인입니다. 그다음 이분 탐색을 할 수 있습니다. 줄의 절반만 남겨 확인하세요.- Hook.
.claude/settings.json을 열고hooks섹션을 임시로[]로 설정합니다.claude를 다시 시작합니다. 작동하나요? 그렇다면 hook 중 하나가 원인입니다. 하나씩 다시 활성화하세요. - MCP 서버. 마찬가지로
~/.claude.json또는.claude/settings.json에서mcpServers섹션을 임시로 빈 객체로 설정한 뒤 다시 시작해 확인합니다. - Skill.
.claude/skills/를 임시 폴더로 옮긴 뒤 실행해 확인합니다.
“임시로 이름을 바꾼다”는 말은 진단 중 파일을 삭제하지 않는다는 뜻입니다. mv나 git stash를 사용하면 해당 계층이 원인이 아닌 것으로 확인될 때 명령 하나로 모두 복원할 수 있습니다.
컨텍스트를 잃지 않고 /cd로 작업 폴더를 바꾸려면 어떻게 해야 하나요?
핵심 요점
Claude Code 2.1.169+의 /cd <path> 명령은 프롬프트 캐시를 잃지 않고 활성 세션의 작업 폴더를 바꿉니다. 현재 프로젝트의 설정이 깨졌을 때 유용합니다. 깨끗한 폴더로 이동해 Claude가 작동하는지 확인한 뒤 돌아올 수 있습니다. 이전에는 세션을 닫고 다시 시작해야 했습니다.
6월 8일자 v2.1.169 변경 로그에는 다음과 같이 나옵니다.
세션 중 프롬프트 캐시를 재설정하지 않고 새 작업 폴더로 전환하는
/cd명령을 추가했습니다.
문제 해결에 왜 유용한지 살펴보겠습니다. ~/work/myapp 프로젝트 폴더에서 Claude Code가 이상하게 동작한다고 가정해 보세요. 이전에는 “이게 제대로 작동하긴 하나?”를 확인하려면 세션을 닫고 다른 폴더로 이동해 다시 시작해야 했습니다. 컨텍스트, 기록, 예열된 프롬프트 캐시를 모두 잃었습니다. 이제는 다음과 같이 할 수 있습니다.
# In the same session:
/cd ~/sandbox/test
Claude는 새 폴더로 전환하고 해당 폴더의 CLAUDE.md가 있으면 시스템 프롬프트를 대체하는 대신 메시지로 읽습니다. 따라서 캐시가 보존됩니다. ~/sandbox/test에서 모든 것이 작동한다면 문제는 ~/work/myapp의 설정에 있었던 것입니다.
6월 12일 v2.1.176에서는 불편한 회귀 문제 하나가 수정됐습니다. /cd를 사용하면 완전히 다시 시작할 때까지 이전 git 브랜치가 표시됐습니다. 이전 버전을 사용 중이라면 업데이트하거나 전환 직후 첫 몇 개 메시지에서는 git status를 무시하세요. 상태가 곧 갱신됩니다.
529 오류에 대비해 대체 모델을 설정하려면 어떻게 해야 하나요?
핵심 요점
v2.1.166에서 Anthropic은 기본 모델이 과부하 상태이거나 사용할 수 없을 때 최대 3개 모델을 순서대로 시도하는 fallbackModel을 추가했습니다. 이 연결은 과부하와 재시도할 수 없는 서버 오류가 발생할 때만 작동합니다. 인증, 결제, 요청 제한, 전송 오류는 대체 모델 연결을 작동시키지 않고 일반 재시도 로직을 따릅니다.
설명된 상황에서는 프로젝트의 긴 작업을 Opus로 주 1회 실행합니다. 10분 뒤 API가 529 Overloaded를 반환하고 세션이 중단됩니다. 이전에는 기다리거나 --model sonnet으로 수동 전환하면서 예열된 컨텍스트를 모두 잃어야 했습니다. second-brain 구조를 사용하는 큰 business/에서는 이 작업에 약 20분이 걸립니다. 이제 전용 메커니즘을 사용할 수 있습니다.
공식 문서의 정확한 인용문은 다음과 같습니다.
기본 모델에 과부하가 걸렸거나 사용할 수 없거나 재시도할 수 없는 다른 서버 오류가 반환되면, Claude Code는 요청을 실패 처리하는 대신 대체 모델로 전환할 수 있습니다. 인증, 결제, 요청 제한, 요청 크기, 전송 오류는 전환을 유발하지 않습니다. 일반적인 재시도 및 오류 처리 경로를 따릅니다.
연결 작동 방식에 대한 설명은 별도로 나와 있습니다.
하나 이상의 대체 모델을 설정하면 Claude Code가 표시된 순서대로 시도하고 전환 시 알림을 표시합니다. 전환은 현재 턴에만 적용되며 다음 메시지에서는 다시 기본 모델을 시도합니다. 중복 제거 후 연결에는 최대 세 모델까지만 허용되며 추가 항목은 무시됩니다.
두 가지 설정 방법이 있습니다. CLI를 사용하는 방법:
claude --fallback-model sonnet,haiku
~/.claude/settings.json을 사용하는 방법:
{
"fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}
요청 제한과 관련해 한 가지 별도 사항이 있습니다. Anthropic은 429 오류가 연결에 전달되지 않도록 의도적으로 처리합니다. 따라서 다음 모델로 전환해 요청 제한을 우회할 수 없습니다. 대체 모델 기능은 기본 모델이 과부하 상태이거나 사용할 수 없거나 재시도할 수 없는 서버 오류(예: 529 Overloaded)를 반환할 때만 작동합니다. 요청 제한에는 일반 재시도 로직과 대기 시간이 적용됩니다.
또 다른 사항으로, 6월 12일 v2.1.174에서 회귀 문제가 수정됐습니다. 압축 작업에서 --fallback-model을 따르지 않던 문제였습니다. 긴 세션이 과부하 중에 압축되면 이 수정 전에는 대체 모델이 호출되지 않았습니다. 긴 세션(/compact, 밤새 실행하는 /loop)을 사용한다면 최소 v2.1.174로 업데이트하세요.
CLAUDE.md, hook, MCP, skill이 원인이라면 무엇을 고쳐야 하나요?
핵심 요점
안전 모드로 원인 계층을 찾은 뒤에는 계층에 따라 다르게 수정해야 합니다. CLAUDE.md는 이분 탐색을 하거나 200줄 미만의 준비된 템플릿으로 되돌립니다. Hook은 종료 코드(2는 차단하고 1은 차단하지 않음)와 로직을 확인합니다. MCP는 서버를 하나 제거하고 확인합니다. Skill은 SKILL.md가 CLAUDE.md와 모순되지 않는지 확인합니다.
계층별 구체적인 전략은 다음과 같습니다.
CLAUDE.md가 원인인 경우
파일을 열어 크기를 확인하세요. 설명된 경험에 따르면 활성 CLAUDE.md는 최대 200줄로 유지하고, 나머지는 프로젝트에 함께 두는 라우터와 보조 문서로 옮기세요(second-brain 전체 구조는 second brain 가이드에 있습니다). 400줄을 넘는다면 거의 틀림없이 원인입니다. 단계:
- 백업을 만듭니다:
cp CLAUDE.md CLAUDE.md.full. - 짧고 작동하는 템플릿으로 되돌립니다. “CLAUDE.md 설정 방법” 가이드에서 바로 사용할 수 있는 템플릿을 찾을 수 있습니다.
- Claude Code를 다시 시작합니다. 확인합니다.
- 작동하면 규칙을 10–20줄의 작은 블록으로 복원하고 각 블록을 복원할 때마다 확인합니다.
- 동작을 깨뜨리는 블록을 찾습니다. 이 H2의 다음 하위 절에서 설명하는 올바른 종료 코드를 사용하는 hook으로 다시 작성합니다.
Hook이 원인인 경우
가장 먼저 확인할 것은 종료 코드가 올바른지 여부입니다. Claude Code hook은 다음을 사용합니다.
- Exit 0 — 정상입니다. 작업이 진행됩니다.
- Exit 1 — 오류지만 차단되지 않습니다. Claude는 아무 일도 없었던 것처럼 계속 진행합니다.
- Exit 2 — 차단 오류입니다. 이 코드만 실제로 작업을 중단합니다.
차단하려고 shell hook에 sys.exit(1) 또는 exit 1을 작성했다면, Claude Code에서는 작업을 중단하지 않고 로그 경고처럼 작동합니다. 2로 변경하세요. Hook과 이런 함정을 피하는 설정 방법은 별도 가이드를 참조하세요.
두 번째로 흔한 경우는 hook이 stdout에 유효하지 않은 JSON을 반환하는 것입니다. Claude Code는 hook 응답을 JSON으로 파싱합니다. 응답에 로그, 진행 표시, 이모지 같은 불필요한 내용이 있으면 hook을 실패로 간주하고 작업을 진행합니다. 규칙: stdout에는 JSON만 출력하고 나머지는 모두 stderr로 보냅니다.
세 번째는 안전 모드에서 숨겨진 ~/.claude/의 항목을 읽는 hook입니다. 이는 정상적인 상황입니다. hook을 수정하는 대신 시작 부분에서 os.environ.get('CLAUDE_CODE_SAFE_MODE')를 확인하고 0으로 종료하도록 수정하세요.
MCP 서버가 원인인 경우
증상: MCP 명령은 사용할 수 있지만 명확한 traceback 없이 failed를 반환합니다. 단계:
claude mcp list를 실행해 어떤 서버가 정의됐는지 확인합니다.~/.claude.json에서 서버를 하나씩 비활성화합니다.claude-server-A키를_claude-server-A로 바꿉니다. 삭제하지 않고 비활성화하는 방법입니다.claude를 다시 시작합니다. 어떤 호출이 작동하는지 확인합니다.- 원인 서버를 찾으면 로그를 확인합니다:
claude mcp logs <name>. - 제3자 서버(
@modelcontextprotocol/server-postgres등)라면 최근 릴리스가 있는지 확인합니다. MCP 생태계는 여전히 불안정하며, Claude Code 업데이트로 서버가 자주 망가집니다.
“MCP가 두 개일 때만 시작 중 충돌”을 겪는다면 MCP 없이 안전 모드에서 동작을 비교하세요.
Skill이 원인인 경우
Skill은 SKILL.md와 .claude/skills/<name>/의 코드로 구성됩니다. 증상: Claude가 skill을 무시하거나, 잘못된 시점에 적용하거나, 적용하더라도 결과가 엉망입니다. 단계:
SKILL.md를 엽니다. 설명을 확인하세요. 1–2문장이어야 하며 어떤 때 사용하는지 구체적으로 설명해야 합니다. “모든 작업을 위한 범용 도우미”라고 적혀 있으면 Claude는 언제 실행해야 할지 이해하지 못합니다.CLAUDE.md와 모순되는 내용이 있는지 확인합니다.CLAUDE.md에는 “항상 테스트를 작성하라”고 되어 있지만 skill 설명에는 “테스트 없이 빠르게 프로토타이핑할 때 사용하라”고 되어 있으면 충돌합니다.- Skill이 외부 명령(npm, python, git)을 사용한다면 시스템 PATH에서 사용할 수 있는지 확인합니다. Skill은 자체적인 최소 환경을 사용합니다.
안전 모드도 실패할 때: 복구 전에 상태를 진단하고 보존하기
핵심 요점
안전 모드 실패에도 설치, 인증, 네트워크, 인프라 원인이 남습니다. claude doctor 증거를 살펴보세요. 결론 없는 보고서가 설정·세션 삭제를 정당화하지는 않습니다. 전체 상태를 먼저 보존·검증하고 진단된 설치만 복구하세요.
사용자 상태 제거는 진단의 지름길이 아닙니다. 아래 검사로 원인을 찾되 불명확하면 증거를 보존하고 더 조사하세요. 설치 복구는 검증된 백업과 기존 계정·자격 저장소 신원을 유지하며 시작합니다.
claude doctor— 자동 진단입니다. Anthropic 문서에는 다음과 같이 적혀 있습니다.
claude --version은 작동하지만 다른 문제가 있다면claude doctor를 실행해 자동 진단 보고서를 생성하세요.
- 충돌하는 설치가 있는지 확인합니다. 많은 사람이 npm 전역 버전과 기본 설치 프로그램을 동시에 설치해 둡니다.
Claude Code가 여러 개 설치되어 있으면 버전 불일치나 예상치 못한 동작이 발생할 수 있습니다.
ANTHROPIC_API_KEY가 OAuth 세션을 가로채는지 확인합니다. “아무것도 안 되고 키가 만료됐다”는 문제의 흔한 원인입니다.
`ANTHROPIC_API_KEY`가 설정되어 있고 확인 절차를 거쳤다면 Claude Code는 구독 OAuth 인증 정보 대신 해당 키를 사용합니다.
해결 방법: 현재 shell 세션에서 unset ANTHROPIC_API_KEY를 실행하거나 ~/.zshrc / ~/.bashrc에서 해당 항목을 제거합니다.
- 진단으로 확인된 설치만 복구하고 사용자 상태 전체를 먼저 보존하세요. 안전 모드 실패나 불명확한 doctor는 데이터 제거의 증거가 아닙니다. 일관된 백업 전에 모든 Claude 세션과 쓰기 프로세스를 중지하세요. 같은 Unix 계정, HOME, 운영체제 자격 저장소, Anthropic 계정을 유지하고 키 회전이나 대체 신원을 만들지 마세요.
아래는 GNU tar를 사용하는 Linux 백업 예시입니다. macOS·Windows는 ACL, 확장 속성, 링크, 메타데이터를 보존하는 도구로 복원까지 검증하세요. GNU 전용 옵션이 작동한다고 가정하지 마세요. 자격 증명과 세션이 들어 있으므로 저장소 밖의 비공개 위치에 보관하세요.
# Run as the same user who owns the Claude state, after stopping writers.
set -eu
umask 077
backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX")
set --
if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then
set -- "$@" .claude
fi
if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then
set -- "$@" .claude.json
fi
[ "$#" -gt 0 ] || exit 1
tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME"
sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256"
(cd "$backup_dir" && sha256sum -c claude-state.sha256)
mkdir "$backup_dir/restore-check"
tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check"
printf 'Verified recovery directory: %s\n' "$backup_dir"
모든 명령이 성공해야 합니다. Git 추적 설정만이 아니라 ignored·untracked 세션과 플러그인을 포함한 기존 .claude 전체와 .claude.json을 보존합니다. 심볼릭 링크나 별도 설정 위치라면 중지하고 실제 대상도 같은 검증 백업에 포함하세요. 링크만 보관해도 대상은 백업되지 않습니다. macOS Keychain 등 외부 저장소는 포함되지 않으므로 신원을 그대로 유지하세요.
진단에서 충돌 원인이 기존 로컬 설치로 특정됐다면 설정과 세션을 지우지 말고 그 설치만 비공개 복구 디렉터리로 옮기세요.
# Use the verified backup_dir from the previous block.
if [ -d "$HOME/.claude/local" ]; then
mv "$HOME/.claude/local" "$backup_dir/legacy-local"
fi
npm 설치도 충돌 원인으로 확인되고 기본 설치를 유지할 때만 제거하세요. .claude나 .claude.json을 지우지 않고 공식 기본 설치 프로그램을 쓰세요.
curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
Windows 기본 설치 명령:
irm https://claude.ai/install.ps1 | iex
복원은 별도로 진행하세요. 쓰기 프로세스를 다시 중지하고 체크섬을 확인해 빈 복구 디렉터리에 추출한 뒤 비교가 성공해야 사용하세요. 옮긴 설치를 돌릴 때는 $HOME/.claude/local이 없는지 먼저 확인하고 $backup_dir/legacy-local을 정확한 경로로 옮기세요. 설정 파일도 현재 대체본을 보존한 뒤 진단된 파일만 복원하고 전체를 무작정 덮어쓰지 마세요. Git 스냅샷만으로 ignored·untracked 세션, 자격 증명, 메타데이터를 보존하지는 못합니다.
Claude Code에 문제가 생겼을 때 하지 말아야 할 일은 무엇인가요?
핵심 요점
설명된 지원 사례에서 발견된 여섯 가지 안티패턴입니다. 진단 전에 키를 변경하기, 처음부터 전체 초기화하기, hook의 UI 오류에 당황하기, 로직을 고치기 전에 hook 종료 코드를 높이기, 안전 모드 안전장치 없이 CLAUDE.md 편집하기, “Claude가 자기 MCP를 고친다”고 믿기입니다. 각각 몇 시간씩 낭비하게 만들며, 모두 불필요합니다.
진단 전에 키를 변경하지 마세요
“인증이 작동하지 않는다”는 문제는 90%의 경우 ANTHROPIC_API_KEY가 구독 인증을 가로채거나, hook UI 버그가 있거나, MCP가 실패한 경우입니다. 키를 교체해도 이런 문제는 해결되지 않지만 한 시간 더 중단될 수 있습니다. 기존 키를 폐기하고 새 키를 발급받아 CI에 다시 서명하고 프로덕션 변수를 업데이트해야 합니다. 먼저 claude --safe-mode를 실행하세요. 작동하나요? 그렇다면 사용자 지정 항목이 문제이며 키를 건드릴 필요가 없습니다.
안전 모드를 시도하기 전에 전체 초기화하지 마세요
안전 모드는 1초 만에 분리된 환경을 제공합니다. .claude 삭제는 세션, MCP 설정, 다른 미추적 상태를 파괴할 수 있습니다. 먼저 진단하고 비공개 백업을 검증한 뒤 원인으로 지목된 설치나 설정 계층만 되돌릴 수 있게 옮기세요.
Hook의 UI 오류에 당황하지 마세요
무엇이든 수정하기 전에 시각적 표시만 믿지 말고 로그를 stderr로 남기거나 명시적으로 출력해 hook이 실제 실행됐는지 확인하세요.
로직을 수정하기 전에 hook 종료 코드를 높이지 마세요
차단 hook이 막지 못하면 exit 2로 바꾸고 끝내고 싶은 마음이 듭니다. 작동하는 수정이지만 또 다른 문제를 감춥니다. 한 달 동안 차단되지 않았다면 hook이 금지하려던 모든 작업이 통과했을 수 있습니다. 먼저 git 로그를 살펴보고 정확히 무엇이 통과했는지 확인하세요. 그런 다음 차단을 추가합니다. 그렇지 않으면 이제 차단해도 이전에 벌어진 일이 되돌려지지 않습니다.
안전 모드 안전장치 없이 프로덕션 CLAUDE.md를 편집하지 마세요
설명된 사례를 보겠습니다. CLAUDE.md를 편집한 뒤 Claude가 이상하게 동작하기 시작합니다. git diff를 실행해 보니 그날 저녁 누군가 저장소에 MCP 서버와 hook도 추가했습니다. 사용자는 자신의 편집을 탓하고 되돌리지만 Claude는 계속 이상하게 동작합니다. 규칙: git revert를 실행하기 전에 claude --safe-mode를 실행하세요. 안전 모드에서도 문제가 계속되면 편집한 내용은 원인이 아니므로 되돌릴 필요가 없습니다.
“Claude가 자기 MCP를 고친다”고 믿지 마세요
흔한 상황은 이렇습니다. Claude에게 “MCP 서버에 특정 도구를 추가해 달라”고 요청합니다. Claude가 정상 작동하던 설정을 다시 작성해 모든 것이 망가지고, 이어서 자신이 일으킨 피해를 여러 턴에 걸쳐 진단하느라 세션 할당량까지 소모합니다. MCP에 문제가 생기면 설정을 직접 확인하세요. 에이전트에게 맡기지 마세요. 도구 모음의 일부도 MCP로 작동하기 때문에 MCP가 망가지면 진단 도구도 제대로 작동하지 않습니다.
문제를 해결한 다음에는 무엇을 해야 하나요?
핵심 요점
Claude Code를 복구한 뒤에는 다시 문제가 생기지 않도록 예방책을 추가하세요. 최소한 사용자 설정에 disableBypassPermissionsMode: "disable"을 적용하고, .env와 git push --force를 차단하는 hook을 설정하며, 장시간 자율 실행을 위한 sandbox를 마련합니다. 예방 가이드는 이 가이드의 짝입니다.
사고를 분석한 뒤 곧바로 작업에 복귀하지 마세요. 같은 문제가 다시 발생하지 않도록 먼저 예방책을 추가합니다. 프로젝트 구조가 담긴 business/ 폴더와 second brain, CLAUDE.md를 구축하는 데 몇 시간을 쓸 수 있고 수동으로 복원하기도 어렵습니다. 이것만으로도 예방책을 마련할 이유는 충분합니다. 최소 구성은 다음과 같습니다.
~/.claude/settings.json에permissions.disableBypassPermissionsMode: "disable"을 설정합니다. 우회 모드를 구조적으로 금지해 실수로--dangerously-skip-permissions를 실행해도 작동하지 않게 합니다.Read(./env*),Bash(git push --force),Write(./node_modules/**)용 hook을 설정합니다. 바람이 아니라 규칙으로 차단해야 할 항목입니다.- 장시간 자율 실행을 위한 sandbox 설정(
/loop,/schedule). - 버릴 컨텍스트를 지정하는 사용자 규칙을 적용한
/compact를 설정해 Claude가 컨텍스트를 과도하게 소비하지 않게 합니다.
4단계 보호 체계 전체는 “밤새 프로젝트를 망가뜨리지 않도록 Claude Code를 설정하는 방법” 가이드에 있습니다. 한 가이드는 /loop를 시작하기 전에 예방하는 방법을, 다른 가이드는 /loop가 이미 무언가를 망가뜨린 뒤 복구하는 방법을 다룹니다. 서로 잘 맞는 한 쌍입니다.
출처
- Anthropic Claude Code 변경 로그 - v2.1.166(
fallbackModel), v2.1.169(안전 모드, /cd), v2.1.174(압축 문제 수정), v2.1.176(/cd의 git 브랜치 표시 문제 수정)를 설명하는 공식 변경 로그. - Anthropic 문서 - 모델 설정 - “대체 모델 연결”, “대체 모델을 작동시킨 원인 확인”, “모델 설정” 절.
- Anthropic 문서 - 설치 및 로그인 문제 해결 - 설치 충돌,
claude doctor,ANTHROPIC_API_KEY가로채기.
실용 자료: Ailoot 문서.
더 많은 자료와 도구: Ailoot.
자세히 보기
Claude Code 복구: 안전 모드, /cd, 대체 모델 | Ailoot: 자주 묻는 질문
안전 모드 실패는 ~/.claude를 지워야 한다는 뜻인가요?
아닙니다. 설치, 인증, 네트워크, 인프라를 더 조사해야 합니다. 불명확한 doctor 결과는 설정·세션 제거의 증거가 아니며 진단된 계층만 복구하세요.
설치 복구 전에 무엇을 보존해야 하나요?
쓰기를 중지하고 세션, 플러그인·MCP, 무시 파일, 파일 메타데이터를 포함한 전체 상태를 백업하세요. 체크섬과 추출을 검증하고 기존 계정·자격 저장소를 유지하며 현재 상태를 무작정 덮어쓰지 말고 진단 계층만 복원하세요.