Code Mode란 무엇인가
Anthropic의 문서는 그 차이점을 두 문장으로 설명합니다. "Code Mode가 없으면 Claude는 Bash, Read, Edit와 같은 도구 호출을 직접 요청하고 각 결과를 읽은 후 다음에 무엇을 할지 결정합니다. Code Mode를 사용하면 Claude는 도구 호출을 수행하는 JavaScript 조각을 작성하고, Claude Code는 해당 코드를 세션에서 실행합니다."
이 기능에는 명확한 경고가 따릅니다. "Code Mode는 실험적 기능이며 기본적으로 꺼져 있습니다. 향후 릴리스에서 변경되거나 제거될 수 있습니다."
문서에서는 다음과 같이 많은 관련 도구 호출이 필요한 작업에 이 모드를 사용해 볼 것을 권장합니다.
- 여러 파일에 걸쳐 반복되는 변경 사항.
- Claude가 읽기 전에 결과를 필터링해야 하는 검색.
- 동시에 실행할 수 있는 여러 독립적인 명령.
developersdigest의 워크스루와 같은 초기 리뷰에서는 이 모드를 켜는 방법을 설명합니다. 장기 작업에서 중요한 부분은 Claude가 무엇을 다시 읽어오는지, 그리고 그 이후 세션에 어떤 일이 일어나는지입니다.
Claude가 실행한 코드에서 다시 읽어오는 내용
이 부분은 Code Mode가 Claude의 context에 남는 내용을 어떻게 바꾸는지에 관한 것입니다.
일반적인 작동 방식에서는 각 도구 호출의 결과가 다음 결정을 내리기 전에 Claude에게 돌아옵니다. Code Mode에서 문서는 다음과 같이 설명합니다. "하나의 코드 조각이 명령을 병렬로 실행하고, 한 결과를 다음 호출에서 사용하며, Claude가 읽어야 할 출력의 일부만 반환할 수 있습니다."
문서의 예시는 재시도 제한(retry limit)을 높여달라는 요청입니다. Claude는 함수를 검색하고, 첫 번째 일치하는 파일을 수정하고, 관련 테스트를 실행한 후 파일 경로와 테스트 출력을 반환하는 코드를 작성합니다. 이 예시에서 검색 출력은 Claude에게 직접 전달되는 대신, 파일 선택을 위해 코드 내부에서 사용됩니다.
이 설계에서 세 가지 결과가 도출됩니다.
- Claude가 읽을 내용을 선택합니다. 코드의 마지막 줄이 반환될 내용을 결정합니다. 중간 결과는 스크립트 내부에 머물 수 있습니다.
- 읽기 전에 필터링이 발생합니다. 수백 개의 일치 항목이 있는 검색 결과가 대화에 도달하기 전에 코드 내에서 좁혀질 수 있습니다.
- 기록이 두 곳에 남습니다. 대화에서는 도구 호출을 볼 수 있고, 코드 자체는 트랜스크립트에 남습니다.
문서는 사용자가 보는 화면을 다음과 같이 설명합니다. "대화에서는 수정 사항의 diff와 같은 도구 호출만 보이고 코드는 보이지 않습니다." 코드를 읽으려면 Ctrl+O를 눌러 트랜스크립트 뷰어를 열어야 하며, 여기서 각 코드 조각은 접힌 Code 행으로 표시됩니다. 이 뷰어가 무엇을 보여주고 뷰마다 어떻게 다른지는 Claude Code의 트랜스크립트 뷰 가이드에서 다루었습니다.
실질적인 결과는 한 단계 이후에 Claude가 알게 되는 내용이 코드가 반환한 값에 달려 있다는 것입니다. 나중에 질문할 때 코드가 필터링해버린 세부 정보가 필요하다면, Claude는 다시 확인해야 할 수도 있습니다.
Code Mode를 켜는 방법
설정은 간단하지만 각 단계마다 알아두어야 할 세부 사항이 있습니다.
버전 확인. Code Mode는 Claude Code v2.1.323 이상 버전이 필요합니다. 이전 버전은 Code Mode 없이 시작됩니다.
환경 변수 설정. Code Mode는 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE에 의해 제어됩니다. 이를 쉘에서 1로 설정하여 시도해 보거나, 사용자 설정 파일의 env 블록에 설정하여 모든 새 세션에서 활성화할 수 있습니다.
여기에는 보안 세부 사항이 있습니다. 문서에 따르면 Claude Code는 프로젝트 설정 파일에 있는 이 변수를 무시합니다. "따라서 클론한 저장소가 사용자 대신 Code Mode를 켤 수 없습니다." 오직 사용자의 쉘과 사용자 설정만 유효합니다.
한 번 확인. 첫 번째 Code Mode 세션 전에 Claude Code는 확인을 요청합니다. 활성화 옵션을 선택하면 Claude Code가 재시작되며, 세션 상단에 Code Mode가 켜져 있고 이 세션은 Code Mode가 켜진 상태에서만 재개될 수 있다는 메시지가 표시됩니다.
도구 호출이 많은 작업 시도. 문서의 샘플 프롬프트는 Claude에게 프로젝트의 모든 Markdown 파일을 읽고 존재하지 않는 로컬 파일에 대한 링크를 나열하도록 요청합니다.
Code Mode 세션이 Code Mode가 켜진 상태에서만 재개되는 이유
이것이 서두의 예시 뒤에 숨겨진 세부 사항입니다.
문서에는 다음과 같은 경고가 포함되어 있습니다. "나중에 Code Mode 세션을 재개하려면 claude --continue 또는 claude --resume을 실행할 때 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE를 1로 유지하십시오. Code Mode가 꺼져 있으면 Claude Code는 세션 재개를 거부합니다."
반대의 경우도 마찬가지입니다. "Code Mode 없이 시작한 세션은 변수가 설정되어 있더라도 Code Mode 없이 재개됩니다."
따라서 모드는 세션이 시작될 때 고정됩니다. 이는 장기 작업에 몇 가지 영향을 미칩니다.
- 항상 유지되는 곳에 변수를 설정하십시오. 하나의 쉘에서만 설정하면 새 터미널에는 적용되지 않습니다. 사용자 설정 파일이 더 안정적인 장소입니다.
- 끄면 이전 세션에 영향을 줍니다. 변수를 제거하면 다시 설정할 때까지 Code Mode 세션을 재개할 수 없습니다.
- 세션을 전환할 수 없습니다. Code Mode 없이 시작된 세션은 그 상태로 유지됩니다.
제한 사항 목록에는 Code Mode 세션이 이동할 수 있는 범위에 대한 내용이 더 있습니다. 터미널에서만 재개할 수 있습니다. Desktop 앱으로 옮기거나 백그라운드 세션으로 전환할 수 없으며, /fork로 백그라운드 복사본을 시작할 수도 없습니다.
끄는 방법 및 조직에서 차단하는 방법
Code Mode를 끄려면 쉘과 사용자 설정에서 변수를 제거한 다음 새 세션을 시작하십시오. 0으로 설정할 수도 있습니다. 문서는 다음과 같이 설명합니다. "한 곳에서 0으로 설정하면 다른 곳에서 1로 설정하더라도 Code Mode는 꺼진 상태를 유지합니다."
관리자는 관리형 설정에서 변수를 0으로 설정하여 모든 사용자에 대해 차단할 수 있습니다. 문서는 사용자가 경험하게 될 상황을 다음과 같이 설명합니다. "Code Mode 세션 중인 사용자는 Claude Code를 종료하거나 재시작할 때까지 해당 세션에 머뭅니다. 그 후 사용자는 Code Mode 없이 시작하게 되며, 0이 설정되어 있는 동안에는 Code Mode 세션을 재개할 수 없습니다."
반대의 경우는 불가능합니다. "관리형 설정에서 사용자를 위해 Code Mode를 켤 수는 없습니다."
조직에서 Code Mode를 사용한 후에 차단하면, Code Mode에서 시작한 세션은 차단이 해제될 때까지 재개할 수 없게 됩니다.
코드에 권한이 적용되는 방식
코드가 사용자의 규칙을 우회하지는 않습니다. 문서에 따르면 Claude가 코드를 실행할 때, 그 안의 각 도구 호출은 사용자의 deny 및 ask 권한 규칙과 Bash와 같은 도구의 일반적인 이름 아래에 있는 PreToolUse hook을 거칩니다.
바뀌는 점은 현재 모드에서 작업을 검토하는 방식입니다.
- auto 모드에서는, 분류기(classifier)가 각 도구 호출이 아닌 실행 전의 각 코드 조각을 검토합니다. 문서에서는 주의 사항을 덧붙입니다. "검색 출력에서 가져온 경로와 같이 런타임에 계산된 값은 보지 못하므로, 반드시 제어해야 하는 호출에 대해서는 규칙이나 hook을 유지하십시오."
- 다른 권한 모드에서는, 코드가 검토 없이 시작되며 해당 모드에서 프롬프트를 띄울 각 도구 호출에 대해 사용자에게 확인을 요청합니다.
문서는 또한 명령 매칭에 대해 경고합니다. app이라는 폴더에서의 git push는 디렉토리를 먼저 변경하는 결합된 명령으로 hook에 도달할 수 있으므로, 쉘 명령을 허용하거나 차단하는 PreToolUse hook은 명령의 각 부분을 확인해야 합니다. 코드 자체를 검사하려면 코드를 실행하는 도구인 REPL과 일치하는 PreToolUse hook을 작성하고 tool_input.code에서 JavaScript를 읽을 수 있습니다.
차단할 수 있는 hook
Hook은 Code Mode에서의 작업을 중단시킬 수도 있으며, 문서에는 두 가지 사례가 나열되어 있습니다.
실패한 PreToolUse hook. Claude가 거부된 도구 호출을 보고하면 오류 텍스트에 이유가 표시됩니다. 문서는 두 가지 메시지를 설명합니다. hook이 시작되지 못했거나, 강제 종료되었거나, 특정 코드로 종료되었음을 의미하는 'hook failed', 그리고 타임아웃되었음을 의미하는 'hook did not finish'입니다. 두 경우 모두 onFailure가 설정되지 않은 경우 호출이 거부됩니다. hook이 실패하거나 타임아웃되어도 호출을 진행하려면 onFailure를 continue로 설정하라고 문서는 조언합니다.
코드 출력을 보는 UserPromptSubmit hook. 코드가 백그라운드에서 실행될 수 있을 때, 해당 이벤트의 command, http, mcp_tool hook도 코드 출력에서 실행된다고 문서는 명시합니다. 이 중 하나가 차단하면 Claude는 출력이 예상되는 위치에 hook의 차단 이유를 보고합니다. 해결책은 입력의 source가 poll_event일 때 hook을 통과시키는 것입니다.
이 두 번째 사례는 context를 추가하거나 Claude에게 도달하는 내용을 필터링하기 위해 UserPromptSubmit hook을 사용하는 경우 중요합니다. Code Mode에서는 동일한 hook이 사용자의 프롬프트 이상의 것을 볼 수 있습니다. 어떤 hook이 Claude를 위해 context를 추가할 수 있고 그 출력이 세션 간에 어떻게 작동하는지는 Claude Code hook 가이드에서 다루었습니다.
애드온에 대한 참고 사항이 하나 더 있습니다. 문서의 트러블슈팅 표에는 도구 호출을 확인하는 설치된 mod가 Code Mode가 시작되지 않는 이유로 나열되어 있습니다. Claude Code v2.1.327 변경 로그에 따르면, 설치된 mod가 도구 호출을 가로채더라도(hook) 더 이상 Code Mode 시작을 거부하지 않으며, 관리자는 여전히 관리형 설정에서 이를 끌 수 있습니다. 이전 메시지가 보인다면 버전을 확인하십시오.
장시간 실행되는 코드
긴 빌드나 테스트를 실행하는 코드는 Claude를 기다리게 하거나 백그라운드에서 실행됩니다.
- 대기: Claude는 코드가 끝난 후 답변하며, 코드는 권한 프롬프트에서 보낸 시간을 포함하여 10분 후에 중단됩니다.
- 백그라운드: Claude와 계속 대화할 수 있으며, 코드는 최대 2시간 동안 실행될 수 있습니다.
백그라운드 코드의 경우, 문서에서는 세션을 auto 또는 bypassPermissions 모드로 시작하라고 권장합니다.
Code Mode가 아직 할 수 없는 일
요구 사항과 제한 사항은 구체적이며, Code Mode가 사용자의 환경에 적합한지 결정하는 요소가 됩니다.
- 인터페이스: 터미널에서의 대화형
claude세션. 문서에 따르면-p, Agent SDK, VS Code 패널, Desktop 앱 또는 클라우드 세션에서는 작동하지 않습니다. - 계정 및 제공자: Claude 구독 또는 Console 계정. 게이트웨이나 Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 플랫폼을 통해서는 작동하지 않습니다.
- 조직 설정: HIPAA 구성 또는 제로 데이터 보존(zero data retention) 환경에서는 사용할 수 없습니다.
- 모델: Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 또는 Fable 5.2.
- 기능: Remote Control, Chrome의 Claude 또는 computer use는 사용할 수 없습니다.
- 에이전트 팀: v2.1.326부터 지원되며, 팀원은 기본 인프로세스(in-process) 표시 모드의 Code Mode에서 실행됩니다.
Code Mode가 시작되지 않으면 Claude Code는 사용 불가능하다는 메시지와 그 이유를 표시하며, /status에서도 이를 확인할 수 있습니다.
사람들이 흔히 겪는 실수
변수 없이 터미널에서 재개 시도. Claude Code는 Code Mode가 꺼진 상태에서 Code Mode 세션을 재개하는 것을 거부합니다.
프로젝트 설정에서 활성화 시도. Claude Code는 해당 위치의 변수를 무시합니다.
Claude가 코드가 건드린 모든 것을 기억할 것이라 기대. Claude는 코드가 반환한 내용만 읽습니다.
실패한 hook이 호출을 통과시킬 것이라 가정. Code Mode에서 실패하거나 타임아웃된 hook은 onFailure를 continue로 설정하지 않는 한 호출을 거부합니다.
해결책: Code Mode 세션을 계속하기 쉽게 만들기
1단계: 사용자 설정에 변수 설정
~/.claude/settings.json의 env 블록에 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE를 추가하여 모든 터미널이 동일한 방식으로 재개되도록 하십시오.
2단계: hook 검토
PreToolUse hook의 타임아웃 및 실패 처리를 확인하고, UserPromptSubmit hook이 poll_event에서 통과되도록 하십시오.
3단계: 나중에 필요한 출력 요청
중요한 단계에서는 Claude에게 요약뿐만 아니라 나중에 참조하고 싶은 세부 정보를 반환하도록 요청하십시오.
4단계: 작업 결정 사항 기록
긴 Code Mode 세션의 결론을 세션 재개 여부에 의존하지 않는 곳에 기록해 두십시오.
MemoryLake에서 설정하기
Code Mode 세션은 Claude가 작업하면서 배운 내용을 보유하지만, 동일한 설정으로 다시 열 수 있을 때만 유효합니다. 어떤 파일이 특정 동작을 담당하는지, 리팩토링이 왜 거기서 멈췄는지, 어떤 테스트가 변경 사항을 보호하는지와 같은 결론은 단일 세션 설정에 의존해서는 안 되는 프로젝트 context입니다.
MemoryLake는 결정 사항, 컨벤션, 그 뒤에 숨겨진 이유와 같은 프로젝트 context를 위한 메모리 레이어입니다. 한 곳에서 관리하며 ChatGPT, Claude Code, Codex와 같이 연결된 어시스턴트에서 사용할 수 있습니다.
사용자는 자신의 언어로 직접 항목을 작성합니다. Claude Code 세션, 트랜스크립트, 설정 파일, hook, CLAUDE.md 파일 또는 벤더의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. Code Mode는 Anthropic이 설명한 방식 그대로 작동합니다.
1단계: API 키 생성
로그인하고 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하십시오.

2단계: 첫 번째 메모리 업로드
해결책의 4단계에서 작성한 내용, 즉 나중 세션이 시작해야 할 결론부터 시작하십시오. 항목당 하나의 결정 사항을 입력합니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결하십시오. Code Mode 여부와 상관없이 새 세션에서 동일한 결정 사항을 활용할 수 있습니다.

실제로 바뀌는 점
첫 번째 차이점은 재개에 대한 의존도가 낮아진다는 것입니다. 세션을 열 수 없더라도 결론은 여전히 사용 가능합니다.
두 번째는 더 깔끔한 context입니다. Claude는 코드가 반환하는 내용을 읽고, 필요한 결정 사항은 긴 히스토리 대신 짧은 항목에서 가져옵니다.
Code Mode를 위한 베스트 프랙티스
관련된 많은 도구 호출에 사용하십시오. 반복적인 수정, 필터링된 검색, 병렬 명령에 가장 적합합니다.
변수를 사용자 설정에 유지하십시오. 세션 재개를 예측 가능하게 만듭니다.
Ctrl+O로 코드를 읽으십시오. 대화에는 코드가 아닌 도구 호출만 표시됩니다.
제어해야 하는 호출에 대한 규칙을 유지하십시오. auto 모드에서 분류기는 런타임 값이 아닌 코드를 검토합니다.
hook 실패 동작을 확인하십시오. 실패하거나 느린 PreToolUse hook은 호출을 거부합니다.
결론을 기록하십시오. 결론을 복구하기 위해 단일 세션 재개에만 의존하지 마십시오.
결론
Code Mode를 사용하면 Claude가 한 단계에서 여러 도구 호출을 수행하는 JavaScript를 작성할 수 있으며, Claude는 코드가 반환하는 출력의 일부만 읽습니다. 이는 실험적 기능이며 기본적으로 꺼져 있고, 최신 모델을 사용하는 대화형 터미널 세션(최소 v2.1.323 버전)으로 제한됩니다.
모드는 세션이 시작될 때 고정됩니다. Code Mode 세션은 변수가 설정된 상태에서만 재개되고, 변수 없이 시작된 세션은 그 상태를 유지하며, 조직 차원의 차단이 발생하면 이전 Code Mode 세션을 재개할 수 없게 됩니다. 권한 규칙과 PreToolUse hook은 여전히 각 호출에 적용되며, 실패하거나 타임아웃된 hook은 호출을 거부합니다. 변수를 사용자 설정에 보관하고, hook을 검토하며, 긴 세션이 내린 결론을 기록해 두십시오.