Claude Code Week 24 실전 — fallbackModel・safe-mode・/cd로 자동화를 멈추지 않는 운용 기술

Claude Code를 스케줄 실행이나 CI에 포함하여 「무인으로 돌리는」 운용을 하고 있을 때, 가장 무서운 것은 사람이 보고 있지 않은 시간에 파이프라인이 멈추는 것입니다. 모델이 일시적으로 과부하(HTTP 529 Overloaded) 상태가 된 것만으로 턴(turn)이 실패하거나, CLAUDE.md나 후크(hook) 설정 실수로 동작이 변해도 원인 파악에 시간이 걸리곤 합니다.

2026년 6월(Week 24・v2.1.166~172)의 Claude Code 업데이트는 바로 이 「멈추지 않고・빠르게 원인을 구분하는」 운용에 효과적인 기능들이 집중적으로 투입되었습니다. 본 기사에서는 새로운 플래그십 모델 소개가 아니라, 자동화 파이프라인을 떨어뜨리지 않고・디버깅하기 쉽게 만들기 위한 3가지 기능(fallbackModel / /cd / --safe-mode)을 그대로 settings.json에 복사해서 붙여넣을 수 있는 형태로 해설합니다.

• fallbackModel로 모델 과부하 시 파이프라인을 멈추지 않는 설정

• /cd로 프롬프트 캐시(prompt cache)를 깨뜨리지 않고 작업 디렉터리를 이동하는 방법

• --safe-mode로 커스터마이징 기인 불량(bug)을 한 번에 구분하는 절차

• 3가지를 조합한 「내결함성(fault tolerance) + 디버깅 용이성」을 갖춘 settings.json 전체 예시

• Claude Code를 스케줄 실행・CI・무인 파이프라인으로 운용하고 있는 엔지니어

• 후크(hook)・스킬(skill)・MCP를 포함한 결과, 불량 구분에 어려움을 겪고 있는 사람

• Claude Code v2.1.172 이후 (claude --version으로 확인) - 설정 파일: ~/.claude/settings.json (사용자) 또는 .claude/settings.json (프로젝트)

기능	해결하는 과제	최소 설정
fallbackModel	모델 과부하(529)로 턴이 중단됨	"fallbackModel": ["sonnet", "haiku"]
/cd	작업 디렉터리 이동 시 캐시가 날아감	/cd ../other-project
--safe-mode	커스터마이징 기인 불량 구분이 느림	claude --safe-mode

3가지 모두 「만약의 사태를 위한 보험」입니다. 평소에는 의식하지 않지만, 장애 발생 시나 조사 시에만 효과를 발휘합니다.

무인 운용 파이프라인에서는 다음과 같은 실패가 일어나기 쉽습니다.

• 일시적인 모델 과부하로 턴이 실패함 — 프라이머리 모델(primary model)이 529를 반환하면 그 자리에서 파이프라인이 멈춥니다. 재실행 스케줄까지 진척도가 제로가 됩니다.
• 여러 프로젝트를 횡단하면 캐시가 낭비됨 — 세션 중에 다른 디렉터리로 이동하면 프롬프트 캐시가 다시 만들어져 레이턴시(latency)와 비용이 증가합니다.
• 「설정 중 무언가가 문제를 일으키고 있다」는 알지만 구분이 안 됨 — CLAUDE.md・후크(hook)・스킬(skill)・MCP를 많이 넣은 결과, 예상치 못한 동작이 나타나도 어떤 커스터마이징이 원인인지 특정하는 데 시간이 걸립니다.

Week 24의 3가지 기능은 이 1~3번에 일대일로 대응합니다.

fallbackModel (v2.1.166・2026-06-06)은 프라이머리 모델이 과부하 또는 이용 불가능할 때 순차적으로 시도할 예비 모델을 최대 3개까지 지정할 수 있는 설정입니다.

settings.json에 배열로 지정합니다.

{
"model": "opus",
"fallbackModel": ["sonnet", "haiku"]
...

CLI에서 일시적으로 지정할 경우에는 쉼표로 구분하여 전달합니다.

claude --fallback-model sonnet,haiku

• 프라이머리가 과부하/이용 불가능할 때 지정된 순서대로 폴백(fallback)하며, 전환 시에 알림이 나옵니다.
• 전환은 해당 턴에만 유효합니다. 다음 메시지에서는 다시 프라이머리부터 시도하기 때문에, 과부하가 해소되면 자동으로 원래 모델로 돌아갑니다.
• 자동 압축(compaction) 처리도 과부하 시에는 폴백 체인(fallback chain)을 존중합니다. 장시간 태스크 도중에 압축이 실행되어도 멈추기 어려워집니다.

fallbackModel

배열(Array) 설정이지만, 대부분의 배열 설정과 달리 파일 간에 병합(Merge)되지 않습니다. 사용자 설정(User settings)과 프로젝트 설정(Project settings) 양쪽에 모두 작성했을 경우, 우선순위가 가장 높은 파일의 정의가 체인(Chain) 전체를 덮어씁니다.

// ~/.claude/settings.json (사용자)
{ "fallbackModel": ["sonnet", "haiku"] }
// .claude/settings.json (프로젝트 · 이쪽이 우선)
...

예비 수단을 두텁게 만들고 싶은데 얇은 체인으로 덮어써 버리는 함정에 빠지기 쉬우므로, 폴백(Fallback)은 "실제로 적용하고 싶은 파일"에 완전히 작성하는 것이 안전합니다.

/cd

(v2.1.169 · 2026-06-08)는 세션을 다른 작업 디렉토리로 프롬프트 캐시(Prompt cache)를 다시 만들지 않고 이동하는 명령어입니다.

/cd ../other-project

• 통상적으로 작업 디렉토리를 변경하면 프롬프트의 전제 조건이 바뀌어 캐시가 작동하지 않게 됩니다.
• /cd는 캐시를 유지한 채 이동하므로, 모노레포(Monorepo) 내의 패키지 간 이동이나 관련 있는 다른 리포지토리(Repository)로의 이동이 저비용으로 가능합니다.
• 이동 대상의 CLAUDE.md는 시스템 프롬프트(System prompt)를 교체하는 것이 아니라 메시지로 추가됩니다. 원래의 컨텍스트(Context)를 유지하면서 이동 대상 고유의 규칙이 덧붙여지는 동작입니다.
• 세션 저장 위치도 이동 대상에 맞춰 전환되므로, --resume / --continue를 통한 세션 복구도 유지됩니다.

여러 프로젝트를 하나의 세션에서 가로지르는 파이프라인에서는 /cd를 사용하는 것만으로 캐시 재구축의 오버헤드(Overhead)를 피할 수 있습니다.

--safe-mode

(v2.1.169)는 모든 커스텀 설정을 무효화하여 Claude Code를 실행하는 트러블슈팅(Troubleshooting)용 플래그입니다. 환경 변수 CLAUDE_CODE_SAFE_MODE로도 활성화할 수 있습니다.

claude --safe-mode
# 또는
CLAUDE_CODE_SAFE_MODE=1 claude

세이프 모드에서 무효화	세이프 모드에서도 유효
CLAUDE.md (프로젝트 지시)	인증
플러그인 (Plugin)	모델 선택
스킬 (Skill)	내장 도구 (Built-in tools)
훅 (Hook)	권한 (Permission)
MCP 서버	Git 상태 · 디렉토리명

"예상치 못한 동작이 발생하지만 원인을 알 수 없을" 때는 다음 단계로 원인을 분리합니다.

• claude --safe-mode로 실행하여 동일한 조작을 재현한다.
• 세이프 모드에서 문제가 사라졌다면 $\rightarrow$ 무효화된 5가지 요소(CLAUDE.md, 플러그인, 스킬, 훅, MCP) 중 하나가 원인.
• 세이프 모드에서도 문제가 남아있다면 $\rightarrow$ 커스텀 설정이 아니라 인증, 모델, 내장 도구, 권한 측면의 문제.

이를 통해 "내 설정이 잘못된 것인지, Claude Code 본체의 동작인지"를 우선 이분할 수 있습니다. 인증이나 모델 선택은 살아있기 때문에, 다시 로그인할 필요 없이 그대로 조사를 계속할 수 있다는 점도 실용적입니다.

3가지 기능을 고려한 무인 운용용 settings.json

최소 구성입니다.

{
"model": "opus",
"fallbackModel": ["sonnet", "haiku"]
...

운용 플로우는 다음과 같습니다.

• 평상시: 프라이머리(Primary, opus)로 실행. fallbackModel은 대기.
• 모델 과부하 시: 자동으로 sonnet $\rightarrow$ haiku 순으로 폴백(Fallback)하여 턴(Turn)을 놓치지 않음. 압축 처리도 마찬가지로 보호됨.
• 여러 프로젝트 가로지르기 시: /cd로 캐시를 유지한 채 이동.
• 결함 조사 시: claude --safe-mode로 실행하여 커스텀 설정 기인 여부를 가장 먼저 분리.

"설정을 한 줄 추가하는 것 · 조사 시 플래그를 하나 붙이는 것"만으로, 무인 파이프라인의 중단 방지와 조사 용이성을 양립할 수 있습니다.

앞서 언급했듯이 fallbackModel은 파일 간에 병합되지 않습니다. 사용자 설정에서 3단계로 구성하더라도, 프로젝트 설정에서 1단계만 정의되어 있다면 그것이 전체를 덮어씁니다. 폴백을 적용하고 싶은 스코프(Scope)에 체인 전체를 완전히 작성해 주세요.

세이프 모드 (safe-mode)는 어디까지나 커스터마이징 (CLAUDE.md, 훅 (Hook), MCP 등)을 불러오지 않는 모드입니다. 인증, 모델 선택, 권한 (Permission)은 유효합니다. "다시 로그인해야 하는 것 아닌가" 하고 경계할 필요 없이, 조사용 원 상태 (Raw state)로서 그대로 사용할 수 있습니다.

이 기능들은 v2.1.166~172에서 순차적으로 도입되었습니다. /cd와 --safe-mode는 v2.1.169, fallbackModel은 v2.1.166이 기점입니다. 작동하지 않을 경우 우선 claude --version을 확인하고, 필요하다면 업데이트해 주세요.

fallbackModel: 최대 3개 모델의 예비 체인 (Chain). 과부하 시에도 턴 (Turn) 단위로 폴백 (Fallback)하며, 압축 처리도 보호됩니다. 단, 파일 간에 병합 (Merge)되지 않는 점에 주의하세요.

/cd: 프롬프트 캐시 (Prompt Cache)를 깨뜨리지 않고 작업 디렉토리 (Working Directory)를 이동. 이동 대상에 CLAUDE.md가 추가되며, --resume/--continue도 유지됩니다.

--safe-mode: 커스터마이징 (CLAUDE.md, 플러그인 (Plugin), 스킬 (Skill), 훅 (Hook), MCP)을 모두 무효화하여 기동. 결함이 커스터마이징으로 인한 것인지 우선적으로 이분할 수 있습니다.

새로운 모델에 대한 화제에 가려지기 쉽지만, Week 24의 진가는 "무인으로 계속 돌리는 운용"을 뒷받침하는 수수하지만 실용적인 기능군에 있습니다. 우선 fallbackModel을 한 줄 추가하는 것부터 시작해 보세요.