본문으로 건너뛰기
JournalTORIS / FIELD NOTES

← 블로그개발 도구

클로드 코드 Code Mode 켜는 법과 v2.1.328 변경점 — 한 번에 JS로 도구 호출하기

Claude Code 실험 기능 Code Mode의 동작 원리, CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 설정법, v2.1.328 최신 패치와 37% 절감 수치의 진실까지 공식 문서로 정리합니다.

Read in English

클로드 코드 Code Mode 켜는 법과 v2.1.328 변경점 — 한 번에 JS로 도구 호출하기

Q. Claude Code의 실험 기능 Code Mode는 무엇이고, 언제 켜면 좋을까요? Code Mode는 Claude가 도구를 한 번에 하나씩 부르는 대신 JavaScript 코드를 직접 작성해 여러 도구 호출을 병렬·연쇄 실행하고, 필요한 결과만 모델 컨텍스트로 돌려주는 실험 기능입니다. 파일 수십 개를 반복 수정하거나 검색 결과를 걸러서 읽어야 할 때 왕복 횟수와 중간 컨텍스트 누적을 크게 줄일 수 있습니다.

⚠️ 정확도 가드레일: 이 글은 2026년 11월 19일 기준 Anthropic 공식 Code Mode 문서, Claude Code v2.1.323~v2.1.328 릴리즈 노트(GitHub), 공식 Changelog를 직접 열어 확인한 내용입니다. 실험 기능(experimental)이라 이후 릴리즈에서 동작이 바뀌거나 제거될 수 있으며, 커뮤니티에서 자주 인용되는 '토큰 37% 절감' 수치는 API의 Programmatic Tool Calling 자료에서 온 값일 뿐 Code Mode 자체의 공식 벤치마크는 공개되지 않았습니다. 직접 대규모 저장소에서 측정한 실측 수치는 포함하지 않았습니다.

30초 요약

  • 작동 방식: CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1로 켜면 Claude가 $·edit() 같은 도구 호출을 담은 JS 코드를 한 번에 실행하고 최종 반환값만 읽습니다.
  • 최신 개선(v2.1.328): 2026년 11월 19일 릴리즈에서 스크립트 종료 후 0.75초 대기 제거, MCP 프롬프트 캐싱 개선, 짧은 도구 설명으로 토큰 절감 등이 반영됐습니다.
  • 사용 조건: 네이티브 빌드 v2.1.323 이상(에이전트 팀 병행은 v2.1.326+), 대화형 터미널 세션 전용, Claude Opus/Sonnet/Haiku 5.5 또는 Fable 5.2 모델이 필요합니다.
  • 제약 사항: Bedrock·Vertex·Foundry, VS Code 패널, Desktop 앱, -p 헤드리스, Remote Control/Chrome 제어에서는 쓸 수 없고 세션 재개(--resume) 시에도 플래그를 1로 유지해야 합니다.

Claude Code 기본 도구 호출과 Code Mode 비교

Code Mode는 도구 호출 방식을 어떻게 바꿀까

Code Mode가 꺼져 있을 때 Claude는 Bash, Read, Edit 같은 도구를 턴마다 하나씩 요청하고 매번 전체 출력을 컨텍스트에 다시 넣습니다. 반면 Code Mode를 켜면 Claude가 JavaScript 한 조각을 작성해 여러 명령을 병렬로 돌리거나 앞선 결과를 다음 호출에 곧바로 넘긴 뒤, 마지막 줄에 평가된 값만 컨텍스트로 돌려줍니다.

대화 화면에는 여전히 편집 diff 같은 도구 호출 결과만 보이며, 실제로 실행된 JS 코드를 확인하려면 Ctrl+O를 눌러 트랜스크립트 뷰어의 접힌 Code 행을 펼치면 됩니다. 토리스 스튜디오에서 다뤘던 Caveman 토큰 압축 실측 검증처럼 에이전트 컨텍스트 낭비를 줄이는 접근과 결이 같지만, 출력 말투가 아니라 도구 오케스트레이션 구조 자체를 바꾼다는 점이 다릅니다.

구분 기본 모드 (Default) Code Mode (Experimental)
도구 호출 방식 한 턴에 하나씩 순차 호출 JS 코드로 병렬·연쇄 호출
컨텍스트에 남는 값 모든 도구 실행 결과 전체 JS 코드가 마지막에 반환한 값만
권한·Hook 검사 호출마다 개별 검사 각 호출마다 동일 검사 + Auto 모드 사전 코드 리뷰
실행 시간 제한 도구별 기본 제한 대기 시 10분, Auto/Bypass 백그라운드 최대 2시간
실행 환경 터미널, VS Code, Desktop, -p, SDK 대화형 터미널(claude) 전용

광고

켜는 방법과 필수 환경 조건

환경 변수 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1을 터미널 세션에 주거나 사용자 설정 ~/.claude/settings.json의 env 블록에 저장하면 됩니다. 다만 저장소 내부 프로젝트 설정 파일에 적힌 값은 보안상 무시되므로, 클론한 저장소가 임의로 Code Mode를 켜지는 못합니다.

# 1) 버전 확인 (v2.1.323 이상 필요, 에이전트 팀 동시 사용은 v2.1.326+)
claude --version

# 2) 이번 세션만 켜서 실행
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

첫 실행 시 Yes, turn on Code Mode 확인을 거치면 상단에 Code Mode (experimental) is on · this session can be resumed only with Code Mode on 안내가 뜹니다. 주의할 점은 모델이 Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 5.2여야 하며, 게이트웨이·Amazon Bedrock·Google Cloud Agent Platform·Microsoft Foundry·HIPAA/ZDR 조직에서는 비활성화된다는 것입니다. DISABLE_TELEMETRY나 OpenTelemetry 내보내기가 켜져 있어도 시작되지 않습니다.

권한 보안과 v2.1.328 최신 패치 내역

Code Mode가 JS로 여러 도구를 묶어 실행하더라도 deny·ask 권한 규칙과 PreToolUse Hook은 내부의 개별 도구 호출(Bash 등)마다 그대로 적용됩니다. 다만 Auto 모드에서는 분류기가 개별 호출이 아니라 실행 전 JS 코드 전체를 검사하므로, 검색 결과로 동적 생성되는 경로까지 막아야 한다면 별도 PreToolUse 규칙을 유지해야 합니다.

11월 12일 v2.1.323 첫 공개 이후 11월 19일 v2.1.328까지 매우 빠른 속도로 안정화 패치가 들어갔습니다. Auto 및 Bypass 모드에서 스크립트 끝마다 걸리던 0.75초 지연을 없앴고, MCP 서버 프롬프트 캐싱과 짧은 도구 설명으로 토큰 소모를 낮췄으며, UserPromptSubmit Hook이 스크립트 출력을 가로채던 동작을 정리해 PostToolUse의 updatedToolOutput으로 일원화했습니다.

실무에서 피해야 할 함정과 '37% 절감' 오해

외부 글에서 자주 보이는 '토큰 37% 절감' 수치는 Code Mode 공식 문서에 없는 값으로, 2025년 Anthropic API의 Programmatic Tool Calling 사례 수치를 끌어다 쓴 것입니다. Code Mode 자체의 공식 토큰·속도 벤치마크는 아직 발표되지 않았으므로, 실제 작업 저장소에서 직접 비교해 판단해야 합니다.

또한 한 번 Code Mode로 시작한 세션은 claude --resume이나 --continue로 이어갈 때도 반드시 환경 변수를 1로 유지해야 열립니다. Remote Control, Claude in Chrome, 컴퓨터 제어(computer use), Desktop 앱으로 세션 이동도 지원되지 않으므로, 브라우저 자동화나 원격 제어가 필요한 작업에는 기존 모드를 쓰는 편이 안전합니다.

토리스의 판단

지금 켜 볼 만한 작업: 수십 개 파일을 훑어 조건에 맞는 줄만 고치는 리팩터링, 로그나 테스트 결과를 필터링해 요약해야 하는 반복 디버깅, 독립적인 린트·빌드·테스트를 동시에 돌려야 하는 터미널 작업에는 v2.1.328 기준 충분히 써 볼 만합니다.

켜지 말아야 할 작업: Chrome 브라우저 연동이나 Remote Control이 필요한 작업, Bedrock/Vertex 같은 클라우드 관리형 환경, CI 파이프라인(-p 비대화형 실행), 혹은 Desktop 앱과 오가며 이어 작업해야 하는 세션은 기본 모드를 유지하세요. 토리스 스튜디오의 다른 에이전트 도구 비교는 개발 프로세스 페이지와 GPT-6.2 아스트라 vs 솔 비교 글에서도 확인할 수 있습니다.

출처

광고

YOUTUBE · TORIS STUDIO

토리스 영상 더 보기