Claude Code v2.1.311이 출시되었습니다. 이번에는 일상적인 사용법과 사내 네트워크 설정 양쪽에 걸친 변경 사항이 포함되어 있습니다.
ultrathink가 Claude 5 계열 모델에서 xhigh effort를 발동하게 되었습니다.
Bedrock / Mantle / Vertex / Foundry에서는 모델 설정을 이렇게 변경해야 합니다. 실행 시 새로운 외부 통신이 발생합니다. downloads.claude.ai
상기 서명된 파일로부터 로드하기 - 200K 토큰 초과로 긴 대화가 중단되는 문제, SubagentStop
훅(hook)의 중복 발동, '재시도 불가' 요청 재시도로 인한 멈춤 현상도 수정되었습니다. -
DISABLE_COMPACT
은 설정 파일이나 mod의 $.env.set에서는 '비활성화하는 방향'으로만 작동하게 되었습니다.
📌 영향을 받는 사용자
- Bedrock / Vertex / Foundry를 통해 Claude Code를 사용하며 외부 통신을 제한하고 있는 사용자 (허용 목록 업데이트 필요)
- 설정 파일이나 mod에서
DISABLE_COMPACT를 사용하는 사용자
SubagentStop
훅으로 알림 또는 후처리 작업을 하는 사용자
CLAUDE_CODE_RETRY_WATCHDOG로 무인 실행하는 사용자
- 대화 터미널에서 Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.1을 사용하는 사용자
이번 변경 사항은 다음 네 가지로 나누어 정리하면 이해하기 쉽습니다.
| 분류 | 내용 | 대응 필요 여부 |
|---|
| effort 운영 | ultrathink의 xhigh화 | 불필요 (사용법 숙지) |
| 네트워크 | downloads.claude.ai로의 통신 추가 | 제한 환경에서는 필수 |
| 컴팩션 | DISABLE_COMPACT의 엄격화 | 설정 검토 필요 |
| 버그 수정 | 훅 중복, 멈춤 현상(hang), MCP 등 | 회피책이 있다면 재검토 |
대화 터미널에서 ultrathink를 입력하면 해당 턴이 xhigh effort로 실행됩니다.
| 항목 | 내용 |
|---|
| 대상 모델 | Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.1 |
| ... | ultrathink를 포함하는 턴이 xhigh effort로 작동함 |
| 작업 중 입력했을 경우 | 진행 중인 턴의 남은 effort가 끌어올려짐 |
| 레인보우 표시 | 키워드로 실제로 effort를 높일 수 있는 위치에만 나타남 |
레인보우 표시는 따옴표 안이나 파일 경로 일부에 ultrathink가 포함된 경우에는 나타나지 않습니다. 표시가 보인다면, effort가 높아졌다고 판단할 수 있습니다.
💡 팁
긴 작업 도중에 '여기는 신중하게 생각해 주었으면 좋겠다'고 생각되면, 그 자리에서 ultrathink를 입력할 수 있습니다. 턴을 처음부터 다시 할 필요 없이 남은 턴의 effort를 높일 수 있습니다.
⚠️ Breaking Change
Bedrock / Mantle / Vertex / Foundry에서 작동하는 Claude Code는 모델 설정을 downloads.claude.ai 상기 서명된 파일로부터 로드합니다. 실행 시 downloads.claude.ai로의 통신이 새롭게 발생합니다.
외부 통신을 제한한 환경이나 폐쇄망에서는 다음 둘 중 하나가 필요합니다.
downloads.claude.ai를 허용 목록에 추가할 것 -
CLAUDE_CODE_MODEL_CATALOG=off를 설정하여 이 메커니즘을 비활성화할 것
Claude Code v2.1.311 업데이트 내용
| 구분 | 내용 |
|---|
| 수정 | 표준 컨텍스트 세션에서 요청이 200K 토큰을 초과할 경우, Usage credits required for 1M context 메시지와 함께 중단되던 문제. 이제는 대화를 압축(compaction)하여 계속 진행할 수 있습니다. |
| ... | DISABLE_COMPACT 설정 시에도 에이전트 팀의 팀원이 기록을 압축하던 문제가 있었습니다. |
| 수정 | DISABLE_COMPACT 설정 시에도 리와인드(rewind) 메뉴에 'Summarize from here', 'Summarize up to here'가 표시되던 문제. |
| 개선 | 압축 응답에 요약이 포함되어 있지 않은 경우, 대화를 대체하기 전에 일반적으로 요약을 다시 요청하도록 수정했습니다. |
| 수정 | 자동 압축 직후, 세션 초반부에 편집했던 MEMORY.md / CLAUDE.md의 오래된 내용이 보이는 문제가 있었습니다. |
| 개선 | /teleport 및 claude --teleport 사용 시, 압축된 클라우드 세션이 마지막 압축 지점부터 로드될 경우 경고를 표시하도록 추가했습니다. |
⚠️ Breaking Change
DISABLE_COMPACT 설정:
이제 이 설정은 설정 파일이나 mod의 $.env.set을 통해서만 비활성화할 수 있습니다. 상위 설정에서 비활성화한 환경을 하위 설정에서 다시 활성화하는 운영 방식을 사용하던 경우 동작이 변경됩니다.
| 문제점 | 수정 후 |
|---|
SubagentStop 훅이 실행 중인 서브 에이전트마다 분당 약 2회 발동했습니다. | 서브 에이전트 종료 시 한 번만 발동합니다. |
API가 재시도하지 않도록 지시한 요청을 다시 시도하여, 턴이 수분 동안 정지하는 문제가 있었습니다. CLAUDE_CODE_RETRY_WATCHDOG의 비인간 실행에서는 무기한으로 멈추기도 했습니다. | 재시도가 불가능하다고 판단된 요청은 더 이상 재시도하지 않습니다. |
| 서브 에이전트 시작 후 연결이 완료된 MCP 서버의 도구를 해당 서브 에이전트가 사용할 수 없었습니다. | 사용 가능하도록 수정되었습니다. |
| MCP 서버가 리소스 읽기에 응답하지 않거나 스킬 다운로드 중에 인터럽트(interrupt)가 타임아웃까지 적용되지 않았습니다. | 수정 완료했습니다. |
- headless / SDK:
--output-format json 및 stream-json을 사용할 경우, 문자열 내의 DEL・C1 제어 문자・유니코드 서식 문자가 ꪪ로 이스케이프되어 출력됩니다. JSON으로 파싱된 값 자체는 변하지 않습니다. 트랜스크립트가 순서와 다르게 저장되는 문제나 취소된 메시지가 남아있는 문제도 수정되었습니다. -
: 효과가 없는 모델에서는 모델명・ID에서 접미사(suffix)와 레이블이 분리됩니다. 지정 자체는 계속 가능합니다. [1m]
접미사 (Suffix):
- self-hosted-runner:
--hold-idle-file 및 --max-hold-min을 추가했습니다. 호스트가 '잔존 프로세스가 있음'이라고 보고하는 동안 유휴 세션을 유지할 수 있습니다. -
- Vertex AI / Foundry / Claude Platform on AWS: 긴 비활성 사고(thinking)가 유휴 상태로 판단되어 중단되던 문제를 수정했습니다. -
- 시작 시간 및 UI: Pro/Max 계정의 경우, 이전 확인 시점으로부터 1시간 이내에 시작하면 두 개의 네트워크 요청을 생략합니다. 긴 목록 항목이 포함된
CLAUDE.md나 수천 줄을 변경하는 Write / Edit의 멈춤 현상도 수정되었습니다. -
- VS Code 확장: 응답 내 코드 블록에 구문 색칠(syntax coloring) 기능이 추가되었습니다. VS Code의 원격 측정 설정(telemetry setting)이 꺼져 있는 동안에는
DISABLE_TELEMETRY를 설정하여 세션을 시작할 수 있습니다 (사용량 메트릭 및 오류 보고 전송 안 함, 기능 플래그도 가져오지 않음). -
- Claude Tag: 분석 화면에 Skills 뷰(Skills View)가 추가되었습니다. Slack 채널에서 각 스킬이 실행된 횟수와 사용되지 않은 스킬을 확인할 수 있습니다.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
| 할 일 | 대상 | 우선순위 |
|---|
downloads.claude.ai 허용 또는 CLAUDE_CODE_MODEL_CATALOG=off 설정 | 클라우드 프로바이더를 통해 외부 통신을 제한하는 환경 | 높음 |
DISABLE_COMPACT 설정 위치 확인 | 설정 파일이나 mod에서 사용하는 사람 | 높음 |
SubagentStop 훅 중복 방지 대책 검토 | 알림(Notification)이나 후처리(Post-processing)를 훅으로 하는 사람 | 중간 |
\uXXXX 이스케이프 영향 확인 | claude -p / SDK의 출력을 원시 문자열로 비교하는 사람 | 중간 |
CLAUDE.md에 추가 | ultrathink나 모델 설정을 팀에서 공유하여 운영하는 사람 | 중간 |
구체적인 확인 절차는 다음과 같습니다.
- 네트워크 제한 확인: Bedrock / Vertex / Foundry를 사용하는 경우, 프록시 또는 방화벽 로그에서
downloads.claude.ai로의 통신이 차단되었는지 확인합니다. -
: 설정 파일이나 mod의 DISABLE_COMPACT에 대한 전수조사($.env.set)를 통해, 켜기(on)로 되돌리려는 의도의 기술이 없는지 확인합니다. -
훅 검토: SubagentStop에서 중복 실행을 방지하는 회피책(배타적 제어 또는 중복 판별 등)을 넣었다면, 불필요한지 검토합니다. 이 회피책을 제거하기 전에 동작 여부를 반드시 확인해야 합니다. -
출력 파서 확인: JSON으로 파싱만 하는 경우에는 영향이 없습니다. 정규 표현식(Regex) 등으로 원시 문자열에 직접 매칭시키는 처리만 대상입니다.
Before (v2.1.311 이전): 특별한 설정은 필요하지 않았습니다.
After (v2.1.311 이후, 통신을 허용할 수 없는 경우):
# 시작 시 downloads.claude.ai로의 통신을 막고 싶을 경우
export CLAUDE_CODE_MODEL_CATALOG=off
claude
통신을 허용할 수 있다면, 비활성화하지 않고 허용 목록에 downloads.claude.ai를 추가하는 것이 서명된 파일에 의한 모델 설정 업데이트를 받을 수 있습니다.
설정 파일에 기재하는 경우의 예시입니다. 이 지정은 컴팩션(compaction)을 끄는 방향으로만 영향을 미칩니다.
{
"env": {
"DISABLE_COMPACT": "1"
...
}
v2.1.311 이후로는 설정 파일이나 mod의 $.env.set에서 컴팩션을 다시 활성화할 수 없습니다.
# 턴 시작 시 지정 (해당 턴이 xhigh effort로 실행됨)
ultrathink 이 마이그레이션 계획의 리스크를 도출하여
# Claude 작업 중 입력하면, 진행 중인 턴의 남은 effort가 증가함
...
공식 변경 데이터에는 다음 추가가 권장됩니다.
+ ## 모델·effort 운영
+ - ultrathink는 Claude 5 계열(Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.1,
+ Anthropic API, 대화 터미널)에서 xhigh effort가 됩니다.
...
- : 대상은 Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.1이며, 작업 중 입력하면 남은 턴의 effort가 증가합니다.
ultrathink는 xhigh effort 스위치가 되었습니다 -
클라우드 프로바이더 사용자는 통신처 추가에 주의 필요: downloads.claude.ai를 허용하거나, CLAUDE_CODE_MODEL_CATALOG=off로 비활성화해야 합니다. 폐쇄망(Closed Network)에서는 이를 놓치면 시작 시 동작에 영향을 줄 수 있습니다. -
: 설정 파일이나 mod의 DISABLE_COMPACT는 일방통행이 되었으며, $.env.set에서는 비활성화만 가능합니다. 아울러, 설정해도 발생했던 컴팩션 오류가 수정되었습니다. -
긴 작업 안정성 향상: 200K 초과에서의 중단, SubagentStop의 중복 발화, 재시도 불가 요청의 멈춤(Hang)(CLAUDE_CODE_RETRY_WATCHDOG)
무인 실행(unattended execution)을 포함하여 수정되었습니다. 영향을 큰 순서대로 확인한다면, '통신 제한 여부', 'DISABLE_COMPACT 설정 위치', '훅 우회책' 세 가지가 있습니다.
자세한 내용은 v2.1.311의 릴리스 노트(release note)를 참조해 주십시오.
