Claude Code Code Mode 켜는 법 — 안 켜질 때 확인할 것

Claude Code Code Mode 켜는 법 — 안 켜질 때 확인할 것

••7분 읽기

한줄평

Code Mode는 환경 변수 하나로 켜지지만 실험 기능이라 제약이 많아요. 여러 파일을 반복해서 고치는 일에만 골라 켜고, 평소엔 끄는 게 낫다고 봐요.

Claude Code에 코드 모드(Code Mode)라는 실험 기능이 생겼어요. Claude가 도구를 하나씩 부르는 대신, 짧은 자바스크립트를 써서 여러 작업을 한 번에 처리하는 방식이에요. 저는 반복 작업이 많은 사람에게는 써 볼 만하지만, 기본으로 켜 둘 기능은 아직 아니라고 봐요.

이 글을 읽으면 Code Mode를 켜고 끄는 법, 켜기 전에 알아 둘 제약, 안 켜질 때 확인할 것을 챙길 수 있어요. 내용은 2026년 11월 16일 기준 공식 문서와 변경 기록(2.1.325까지)으로 확인했어요.

광고

Claude Code Code Mode는 무엇이 다른가요?

평소의 Claude Code는 한 걸음씩 움직여요. 파일을 찾고, 결과를 읽고, 다음에 무엇을 할지 정해요. 도구를 한 번 부를 때마다 결과를 다시 읽는 거예요.

Code Mode에서는 Claude가 그 과정을 자바스크립트로 미리 써요. 코드 한 덩어리 안에서 명령을 동시에 돌리고, 앞의 결과를 다음 작업에 넘겨요. 그리고 필요한 결과만 골라서 읽어요.

화면에서 보이는 건 평소와 비슷해요. 파일 수정 내용(diff) 같은 도구 호출만 보이고, 코드는 숨겨져 있어요. 코드를 보려면 Ctrl+O로 대화 기록 화면을 열고 Code 줄을 펼치면 돼요.

공식 문서가 꼽는 잘 맞는 작업은 세 가지예요.

  • 여러 파일에 같은 수정을 반복하는 일
  • 검색 결과를 걸러서 읽어야 하는 일
  • 서로 상관없는 명령 여러 개를 동시에 돌리는 일

Code Mode는 어떻게 켜나요?

순서는 네 단계예요.

  1. claude --version으로 버전을 확인해요. v2.1.323 이상이어야 하고, 낮으면 claude update를 실행해요.
  2. 환경 변수 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE를 1로 두고 Claude Code를 시작해요.
  3. 처음 한 번 확인 창이 뜨면 Yes, turn on Code Mode를 골라요.
  4. 다시 시작된 세션 위쪽에 Code Mode (experimental) is on 줄이 보이면 성공이에요.

한 번만 써 볼 때는 터미널에서 이렇게 실행해요.

# macOS, Linux, WSL
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

Windows PowerShell이라면 $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"을 먼저 실행하고 claude를 시작해요.

매번 켜고 싶다면 사용자 설정 파일 ~/.claude/settings.json에 넣어요.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

이 값은 프로젝트 설정 파일에 넣으면 무시돼요. 남이 만든 저장소를 클론했을 때 Code Mode가 몰래 켜지지 않게 막아 둔 거예요. 저는 이 결정이 맞다고 봐요. 설정 파일이 어디에 있는지 헷갈리면 Claude Code settings.json 위치와 설정법을 보세요.

끌 때는 셸과 설정 파일에서 이 변수를 지우거나 값을 0으로 바꿔요. 어느 한 곳이라도 0이면 꺼진 상태가 유지돼요.

광고

켜기 전에 무엇을 알아 둬야 하나요?

실험 기능이라 조건이 꽤 까다로워요. 공식 문서 기준 주요 조건은 이래요.

항목조건
계정Claude 구독 또는 Console 계정 (Bedrock·게이트웨이 경유는 안 됨)
모델Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.2
실행 환경터미널의 대화형 claude 세션 (-p, VS Code 패널, 데스크톱 앱은 안 됨)
설치 방식네이티브 빌드 (Windows는 Git for Windows 필요)

제가 가장 신경 쓰이는 제약은 세션 이어 하기예요. Code Mode로 시작한 세션은 Code Mode를 켠 상태에서만 claude --continue나 --resume으로 이어 갈 수 있어요. 변수를 지운 채 열면 Claude Code가 이어 하기를 거부해요.

몇 가지가 더 있어요.

  • 기다리는 코드는 10분이 지나면 멈춰요. Auto 모드로 시작하면 백그라운드에서 최대 2시간까지 돌아요.
  • 원격 조종(Remote Control), Claude in Chrome, 컴퓨터 사용 기능은 같이 못 써요.
  • 세션을 데스크톱 앱으로 옮기거나 백그라운드 세션으로 바꿀 수 없어요.

권한 확인 방식도 조금 달라져요. 거부(deny)·확인(ask) 규칙과 훅은 코드 안의 도구 호출마다 그대로 적용돼요. 다만 Auto 모드의 자동 검사기는 도구 호출 하나하나가 아니라 코드 덩어리를 통째로 봐요. 실행 중에 정해지는 값, 예를 들어 검색 결과에서 뽑은 경로는 검사기가 미리 못 봐요. 꼭 막아야 하는 명령은 규칙으로 막아 두세요. 규칙 쓰는 법은 Claude Code Auto 모드 가이드에 정리해 뒀어요.

Code Mode가 안 켜질 때는 무엇을 확인하나요?

세션 위쪽에 Code Mode (experimental) isn't available이 뜨면 켜지지 않은 거예요. 같은 줄에 이유가 붙고, /status에서도 볼 수 있어요. 자주 만날 만한 이유를 추렸어요.

이유에 이 말이 있으면할 일
it isn't open to your account yet버전이 v2.1.323 미만이면 업데이트. 이상인데도 뜨면 다른 날 다시 시도
it only works with the Anthropic API클라우드·게이트웨이 경유 설정과 ANTHROPIC_BASE_URL 제거
it doesn't work with an API key helperapiKeyHelper, ANTHROPIC_AUTH_TOKEN 제거 후 로그인
it only works with Opus 5.5, Sonnet 5.5 and later models--model opus처럼 지원 모델로 시작
it needs settings that Claude Code downloads from AnthropicDISABLE_TELEMETRY 같은 변수 해제
it can't be used together with agent teams yetCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 해제

아무 줄도 안 보이면 버전부터 확인하세요. 그다음 셸이나 사용자 설정에 1이 들어 있는지 봐요. 어딘가 남아 있는 0도 지워야 해요.

stable 채널을 쓰면 업데이트해도 v2.1.323에 바로 못 닿을 수 있어요. 이때는 기다리거나 latest 채널로 바꿔야 해요.

광고

저는 언제 Code Mode를 켜나요?

제 기준은 단순해요. 같은 일을 파일 수십 개에 반복할 때만 한 번짜리 명령으로 켜요. 링크 점검, 이름 일괄 변경, 여러 테스트 동시 실행 같은 일이에요. 저는 이런 일이 도구를 하나씩 부르는 방식보다 Code Mode에 잘 맞는다고 봐요.

평소 작업에는 켜 두지 않아요. 이어 하기 제약이 귀찮고, 실험 기능은 언제든 바뀌거나 사라질 수 있다고 공식 문서에 적혀 있거든요. 실제로 11월 13일 2.1.325에서도 Code Mode 관련 버그 수정이 세 건 들어갔어요. 저는 몇 번의 업데이트를 더 지켜본 뒤에 기본값으로 둘지 정할 생각이에요.

자주 묻는 질문

Code Mode는 유료 기능인가요?

공식 문서에 별도 요금 안내는 없어요. Claude 구독이나 Console 계정이 있으면 조건만 맞춰서 켤 수 있어요.

Code Mode를 켜면 프롬프트를 다르게 써야 하나요?

아니요. 평소처럼 할 일을 말하면 Claude가 알아서 코드를 써요. 다만 여러 파일에 걸친 일을 한 번에 맡길수록 차이를 느끼기 쉬워요.

회사에서 Code Mode를 막을 수 있나요?

네. 관리자 설정(managed settings)의 env에 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE를 "0"으로 넣으면 조직 전체에서 꺼져요. 반대로 관리자 설정으로 강제로 켤 수는 없어요.

VS Code나 데스크톱 앱에서도 되나요?

2026년 11월 16일 기준으로는 안 돼요. 터미널의 대화형 세션에서만 작동해요.


참고 문서: Claude Code Run tool calls from code with Code Mode · Claude Code changelog (2.1.323, 2026년 11월 12일)

광고

T
TomAI 코딩 도구를 매일 쓰는 개발자

Claude Code, OpenCode 같은 AI 코딩 도구를 직접 쓰면서 AI 업계의 변화를 개발자 관점에서 기록합니다. 단순 번역이 아니라 써본 경험과 해석을 함께 남기려고 해요.