claudekit / updates / claude-code-2-1-311
[ PATCH · ]

Claude Code 2.1.311

`ultrathink`가 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1에서 xhigh effort로 실행되고, self-hosted runner에 유휴 세션을 붙잡아 두는 옵션이 추가됐습니다. 200K 토큰을 넘긴 표준 컨텍스트 세션이 "Usage credits required for 1M context"로 멈추던 문제, 긴 목록 항목이 든 CLAUDE.md 때문에 시작이 오래 멈추던 문제 등 50건이 넘는 버그가 수정됐습니다.

Claude Code
공식 발표 →

이 글은 공식 문서를 바탕으로 요약·정리한 내용입니다.

무엇이 바뀌었나?

Claude Code 2.1.311이 2026년 10월 26일 출시됐습니다. ultrathink가 최신 모델에서 xhigh effort로 동작하도록 바뀌었고, Bedrock, Mantle, Vertex, Foundry에서는 모델 설정을 서명된 파일에서 불러오기 시작합니다. 수정은 대부분 안정성에 집중됐습니다. 시작과 파일 편집 중 멈춤, 컨텍스트 한도와 압축, 서브에이전트와 백그라운드 세션, MCP 관리 명령, Remote Control과 클라우드 세션에 걸쳐 50건이 넘는 문제가 고쳐졌습니다.

새 기능

  • self-hosted runner의 --hold-idle-file, --max-hold-min 옵션

    세션이 할 일을 마쳐도 세션이 띄워 둔 프로세스는 호스트에서 계속 실행 중일 수 있습니다. 이제 self-hosted-runner에 두 옵션이 추가되어, 그런 프로세스가 남아 있다고 호스트가 알려 오는 동안 유휴 세션을 유지할 수 있습니다.

  • Explanatory 출력 스타일 안내 팁

    Claude에게 설명을 요청하면 이제 Explanatory 출력 스타일(설명 위주로 답하는 스타일)을 알려 주는 팁이 표시됩니다.

  • [VS Code] 코드 블록 구문 강조

    VS Code 확장에서 Claude 응답의 코드 블록이 단색으로 표시됐습니다. 이제 밝은 테마, 어두운 테마, 고대비 어두운 테마에서 구문 강조가 적용됩니다.

  • [VS Code] 느린 UserPromptSubmit 훅 진행 표시

    UserPromptSubmit 훅이 오래 걸리면 무엇을 기다리는지 알 수 없었습니다. 이제 “Running UserPromptSubmit hooks” 진행 표시와 스크린 리더 안내가 나옵니다.

  • [Claude Tag] 스킬 사용 현황 보기

    Claude Tag 분석 화면에 Skills 보기가 추가되어, Slack 채널에 연결한 스킬마다 Claude가 얼마나 자주 실행하는지, 어떤 스킬이 쓰이지 않는지 확인할 수 있습니다. 관리자 설정에는 Usage 링크가 생겼습니다.

주요 개선

  • ultrathink가 xhigh effort로 실행

    이제 대화형 터미널에서 ultrathink를 입력하면, Anthropic API를 통해 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1을 쓸 때 해당 턴이 xhigh effort로 실행됩니다. Claude가 작업하는 도중에 입력하면 그 턴의 남은 부분의 effort가 올라갑니다. 무지개색 강조도 effort를 실제로 올릴 수 있는 위치에서만 표시되며, 따옴표 안이나 파일 경로의 일부로 쓰인 단어에는 표시되지 않습니다.

  • Bedrock, Mantle, Vertex, Foundry의 모델 설정 파일

    이제 이 환경의 Claude Code는 downloads.claude.ai에 있는 서명된 파일에서 모델 설정을 불러옵니다. 끄려면 CLAUDE_CODE_MODEL_CATALOG=off를 설정합니다.

  • 시작 속도 개선

    Pro, Max 계정은 마지막 확인 후 1시간 안에 다시 실행하면 네트워크 요청 두 개를 건너뛰어 더 빨리 시작합니다. claude --model opus처럼 옵션과 그 값만 넘기는 실행도 더 빨라졌습니다.

  • 압축 결과에 요약이 빠졌을 때 다시 요청

    압축(compaction) 과정에서 모델 응답에 요약이 없으면 그대로 대화를 대체할 위험이 있었습니다. 이제 Claude Code는 대화를 대체하기 전에 대부분 요약을 한 번 더 요청합니다.

  • 시간 초과된 셸 명령의 결과 표시

    셸 명령이 시간 제한에 걸리면 지금까지의 출력을 알기 어려웠습니다. 이제 결과에 그때까지의 출력이 표시되고, 명령이 백그라운드에서 계속 실행 중이라는 점도 알려 줍니다.

  • “Connection dropped” 오류 안내

    이제 이 API 오류가 먼저 살펴볼 곳을 알려 줍니다. 사용 중인 프록시나 게이트웨이가 있으면 그쪽을, 없으면 VPN이나 방화벽을 확인하라고 안내합니다. Anthropic API에만 적용되며 Bedrock, Vertex, Foundry는 바뀌지 않았습니다.

  • 백그라운드 세션 종료 메시지

    백그라운드 세션의 프로세스가 끝나면 실제로는 일어나지 않을 재시작을 약속하는 메시지가 나왔습니다. 이제 그런 문구를 빼고 세션을 다시 이어 가는(resume) 방법을 알려 줍니다.

  • /teleport의 압축된 클라우드 세션 경고

    /teleport와 claude --teleport로 압축된 클라우드 세션을 불러오면 마지막 압축 시점부터만 로드되어, 요약된 이전 메시지가 로컬 사본에 없습니다. 이제 이 점을 경고합니다.

  • DISABLE_COMPACT는 압축을 끄는 방향으로만 동작

    이제 설정 파일과 mod의 $.env.set에서 지정한 DISABLE_COMPACT는 압축을 끄는 데만 쓰이고, 다시 켜는 데는 쓰이지 않습니다.

  • [1m] 접미사 정리

    이제 [1m] 접미사가 아무 효과가 없는 모델에서는 모델 이름과 ID에서 접미사와 라벨이 빠집니다. 접미사를 붙여도 계속 받아들입니다.

  • --output-format json, stream-json 출력의 제어 문자 처리

    이제 문자열 안의 DEL, C1 제어 문자, Unicode 서식 문자를 \uXXXX 이스케이프로 씁니다. 파싱한 값은 같습니다.

  • 설정 파일 권한 규칙 경고는 한 번만

    설정 파일의 권한 규칙에 대한 시작 경고가 실행할 때마다 반복됐습니다. 이제 규칙이 바뀌기 전까지 사용자당 한 번만 표시됩니다.

  • CLAUDE_CODE_SYNC_SKILLS 사용 세션의 스킬 목록 재사용

    CLAUDE_CODE_SYNC_SKILLS를 설정하고 기능 플래그 가져오기를 끈 세션은, 같은 컴퓨터의 다른 세션이 가져온 claude.ai 스킬 목록을 10분 이내라면 재사용합니다.

  • Artifact 도구의 페이지, 문서 선택 기준

    이제 설명 자료나 시각적, 인터랙티브 작업은 artifact 페이지로 만들고, 문서는 사람들이 계속 편집하거나 주고받는 글에 씁니다. 여러 보기가 있는 artifact는 링크의 #name으로 각 보기를 연결합니다.

  • Slack 커넥터의 채널 규칙 확인

    이제 사용자가 직접 지정하지 않은 채널에 메시지를 보내기 전에 Claude가 채널 주제(topic)에 적힌 게시 규칙을 확인합니다.

  • [VS Code] VS Code 텔레메트리 설정 존중

    이제 VS Code의 텔레메트리 설정이 꺼져 있으면 확장이 DISABLE_TELEMETRY를 설정한 채 Claude Code 세션을 시작합니다. 사용 지표와 오류 보고를 보내지 않고 기능 플래그도 가져오지 않습니다. 세션 목록 사이드바는 Web 탭을 처음 열 때 Web 세션을 불러옵니다.

  • [Claude Tag] 보고할 내용이 없는 루틴 실행

    새 세션에서 실행되는 Claude Tag 루틴이 보고할 내용이 없어도 채널에 의미 없는 메시지를 남겼습니다. 이제 메시지 없이 끝낼 수 있습니다.

  • [Code Review] 일시적 오류 자동 재시도

    일시적인 서버 오류로 리뷰 세션이 시작되지 못하면 이제 한 번 자동으로 다시 시도하고, check run에 그 사실을 표시합니다. 자동 재시도에서도 모델이 변경을 분석하지 못하면, 더 이상 자동 리뷰가 시작되지 않는다고 알려 줍니다.

  • 기타 개선 — /code-review는 effort 수준을 맨 앞에 두고 max는 요청받을 때만 쓰도록 Claude에게 안내합니다. 에이전트 보기에서 Ctrl+D는 입력이 비어 있을 때 두 번 누르면 종료됩니다. 전체 화면 목록의 스크롤바 클릭은 마우스 버튼을 뗄 때 동작합니다. claude purge는 이 컴퓨터의 데이터만 지우며 Anthropic에 저장된 데이터는 지우지 않는다고 밝힙니다. 붙여 넣은 로그인 코드가 거부되면 만료됐거나 이미 사용됐을 수 있으니 다시 로그인하라고 안내합니다. 스크린 리더 모드의 권한 규칙 삭제, 질문 목록 안내도 개선됐습니다.

주요 버그 수정

멈춤과 응답 지연

  • CLAUDE.md에 아주 긴 목록 항목이 있으면 시작할 때와 파일을 읽거나 편집한 뒤 오래 멈추던 문제 수정.
  • MCP 서버가 리소스 읽기에 답하지 않았거나 스킬을 내려받는 중일 때 Claude를 중단해도 시간 초과가 될 때까지 반영되지 않던 문제 수정.
  • 파일의 수천 줄을 바꿀 때 Write, Edit가 실행 후 최대 5초 동안 멈추고 변경된 줄을 0으로 보고하던 문제 수정.
  • API가 재시도하지 말라고 표시한 요청을 Claude Code가 재시도해, 턴이 몇 분씩 잡혀 있거나 무인 재시도 모드(CLAUDE_CODE_RETRY_WATCHDOG)에서는 끝없이 멈추던 문제 수정.
  • Google Vertex AI, Microsoft Foundry, Claude Platform on AWS에서 오래 이어지는 숨은 사고(thinking)가 유휴 상태로 판단되어 끊기던 문제 수정.
  • Cowork 클라우드 세션에서 WebFetch, WebSearch가 응답이 멈추면 계속 대기하던 문제 수정. 이제 끝나지 않은 요청은 300초 후 실패합니다.

컨텍스트와 압축

  • 표준 컨텍스트 세션에서 요청이 200K 토큰을 넘으면 “Usage credits required for 1M context”와 함께 멈추던 문제 수정. 이제 대화를 압축하고 계속 진행합니다.
  • 세션 초반에 MEMORY.md나 CLAUDE.md를 편집했으면 자동 압축 직후 Claude가 예전 내용을 보던 문제 수정.
  • claude -p와 SDK 세션이 대화 기록 메시지를 순서가 뒤바뀐 채 저장하거나 되돌린 메시지를 남겨 두던 문제 수정.
  • DISABLE_COMPACT를 설정해도 에이전트 팀원이 기록을 압축하고, 되감기(rewind) 메뉴에 “Summarize from here”, “Summarize up to here”가 표시되던 문제 수정.

서브에이전트와 백그라운드 세션

  • 서브에이전트가 시작된 뒤에 연결을 마친 MCP 서버의 도구를 서브에이전트가 쓰지 못하던 문제 수정.
  • SubagentStop 훅이 서브에이전트가 끝날 때 한 번이 아니라 실행 중인 서브에이전트마다 1분에 두 번꼴로 실행되던 문제 수정.
  • 서브에이전트가 시작한 백그라운드 서브에이전트가 아직 작업 중인데 격리된 worktree가 삭제되던 문제 수정.
  • auto mode에서 자기 셸을 기다리는 백그라운드 에이전트가 깨어날 때마다 새 메인 대화 턴을 시작하던 문제 수정.
  • 연결돼 있거나 고정됐거나 예약 작업, 깨우기가 설정된 백그라운드 세션이 턴 사이에 죽으면 다시 시작되지 않던 문제 수정.
  • 클라우드나 백그라운드 세션이 다시 시작되면 끝난 /code-review나 서브에이전트로 실행되는 다른 스킬이 한 번 더 실행되던 문제 수정.
  • 에이전트 팀 세션을 --resume, --continue, /resume, --session-id로 다시 열면(/clear나 비정상 종료 후 포함) 작업 목록이 비어 보이고, /branch가 원래 세션의 목록에 쓰던 문제 수정.
  • “background service did not respond” 오류가 비활성화된 claude daemon restart를 권하던 문제 수정. 이제 claude daemon stop --any를 권하고, 이 명령이 백그라운드 세션을 끝낸다는 점도 알려 줍니다.
  • claude respawn <id>가 일치하는 백그라운드 세션이 없다고 알리기 전에 백그라운드 서비스부터 시작하던 문제 수정.

MCP와 플러그인

  • 저장소 루트 아래 폴더에서 claude mcp add, claude mcp remove, /mcp를 실행하면 local scope 서버를 담은 ~/.claude.json의 프로젝트 항목 대신 현재 폴더 이름을 표시하던 문제 수정.
  • claude mcp list, claude mcp get이 연결 실패 줄에 오류 코드를 두 번 표시하던 문제(예: ENOENT: ENOENT: …) 수정.
  • 로그인 없이 동작하는 원격 서버를 “Clear authentication” 후 /mcp가 실패로 표시하고, 자격 증명을 보내지 않는 원격 서버를 “authenticated”로 표시하던 문제 수정.
  • 최상위에 빈 .mcp.json이 있는 --plugin-dir 폴더가 여러 플러그인이 아니라 하나의 플러그인으로 로드되던 문제 수정.

도구와 셸

  • Bash 도구 설명이 작업 디렉터리가 호출 사이에 항상 유지된다고 잘못 안내하던 문제 수정.
  • Bash 도구는 zsh를 쓰는데 환경 정보에 fish처럼 명령이 실행되지 않는 셸이 적혀 있던 문제 수정.
  • @ 파일 선택기가 git이 무시하는 파일을 다시 포함시키는 .ignore, .rgignore의 부정 규칙을 무시하던 문제 수정.
  • ! open /tmp/shot.png처럼 이미지 파일을 언급하는 텍스트를 붙여 넣으면 이미지가 첨부되고 프롬프트에서 경로가 사라지던 문제 수정.
  • "\"나 (\)처럼 따옴표나 괄호 안에 홀로 있는 백슬래시가 Claude 응답에서 사라지던 문제 수정.
  • 한 줄이 터미널 폭보다 넓을 때 Write 도구의 파일 미리보기가 행을 건너뛰고 숨은 줄 수를 잘못 세던 문제 수정.
  • Linux에서 --plugin-dir 폴더가 추가 디렉터리이기도 하고 permissions.blockReadsOutsideWorkingDirectories가 켜져 있으면 샌드박스 Bash 명령이 bwrap: Can't create file로 실패하던 문제 수정.

Remote Control, 클라우드, self-hosted runner

  • 네트워크 프록시가 시작 요청을 막으면 Remote Control 세션이 약 2분 동안 “Connecting”에 머물던 문제 수정.
  • Claude가 클라우드나 Remote Control 세션에 보낸 메시지가 Claude 모바일 앱에서 사용자 본인의 메시지로 보이던 문제 수정.
  • Remote Control이나 클라우드 세션으로 보낸 첨부 파일이 디스크 공간 부족으로 저장되지 않거나 20개를 넘는 첨부가 빠졌을 때 Claude가 그 이유를 알지 못하던 문제 수정.
  • 플러그인이나 설정에 agent가 지정돼 있으면 Cowork 클라우드 세션이 재시작 후 커넥터와 대부분의 도구를 잃던 문제 수정. 이제 Cowork 클라우드 세션은 이 설정을 무시합니다.
  • self-hosted runner에서 추가한 읽기 전용 저장소가 속도 제한(HTTP 429, 또는 75로 종료하는 git 래퍼)에 걸리면 세션이 시작되지 않던 문제 수정. 이제 그 저장소 없이 시작합니다.

화면과 안내 메시지

  • plan mode에서 계획 모델이 세션 모델과 다를 때 /effort가 프롬프트 캐시 미스를 경고하지 않던 문제 수정.
  • /usage의 “What’s contributing to your limits usage?”에 큰 프롬프트 캐시 미스가 표시되지 않던 문제 수정.
  • /ide가 VS Code 확장 설치가 끝나기 전이나 실패했을 때 설치됐다고 알리고, 아무것도 설치하지 않았는데 JetBrains 플러그인을 설치했다고 알리던 문제 수정.
  • 구독을 쓸 수 없을 때 Claude Pro, Max 구독자에게 관리자에게 문의하라고 안내하던 문제 수정. 이제 결제 설정으로 안내합니다.
  • /rewind 확인 창이 이후 메시지가 삭제되는데도 대화가 “will be forked”라고 하고, 코드 복원이 수동 편집과 Bash 편집에는 영향을 주지 않는다고 잘못 경고하던 문제 수정.
  • 에이전트 채팅 탭에서 ↑로 아직 전달 대기 중인 메시지를 불러와 다시 보내면 같은 메시지가 두 번 전송되던 문제 수정.
  • 넓은 전체 화면 터미널에서 보여 줄 내용이 없는데도 편집 후 diff 창이 저절로 열리던 문제 수정.
  • 스크린 리더 모드의 계획 승인에서 Escape로 닫은 의견이 그대로 전송되던 문제 수정.
  • 링크를 지원하는 터미널에서 연 백그라운드 세션의 상태 표시줄 링크가 일반 텍스트로 남던 문제, 프롬프트에 입력이 있을 때 피드백 초안 카드의 단축키 안내가 표시되던 문제 수정.

VS Code 확장

  • VS Code나 JetBrains 패널에서 보낸 사용자 지정 스킬, 슬래시 명령에 일반 메시지처럼 열린 파일이나 선택한 줄이 포함되지 않던 문제 수정.
  • macOS와 Linux에서 PATH를 읽기 위해 로그인 셸의 시작 파일을 실행하는 동안 확장 호스트가 멈추던 문제 수정.
  • 도구 결과의 이미지를 클릭하거나 미리보기를 닫으면 결과 텍스트가 편집기 탭에 함께 열리던 문제 수정.
  • Send 버튼으로 메시지를 보낸 뒤에도 음성 받아쓰기가 계속 녹음되던 문제 수정. 이제 Enter와 마찬가지로 보내기 전에 받아쓰기를 멈춥니다.

Cloud sessions

  • 소유자가 조직을 떠났다가 다시 들어오면 Anthropic 호스팅 환경의 루틴이 잠긴 채로 남던 문제 수정. 이제 소유자가 다시 켤 수 있습니다.
  • 편집 대화 상자가 이미 닫힌 뒤 루틴 API 토큰 삭제나 재발급이 실패하면 아무 표시도 없던 문제 수정. 이제 오류 알림이 뜹니다.
  • 관리자 대화 상자를 포함한 클라우드 환경 대화 상자가 중복된 이름을 받아들이던 문제 수정.

알아두면 좋은 점

  • Bedrock, Mantle, Vertex, Foundry를 쓴다면 이제 Claude Code가 downloads.claude.ai의 서명된 파일에서 모델 설정을 불러옵니다. 이 동작을 원하지 않으면 CLAUDE_CODE_MODEL_CATALOG=off로 끌 수 있습니다.
  • ultrathink를 쓴다면 Anthropic API에서 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1을 쓸 때 턴이 xhigh effort로 실행됩니다. 작업 도중에 입력해도 그 턴의 남은 부분에 적용됩니다.
  • 200K 토큰을 넘겨 “Usage credits required for 1M context”로 세션이 멈췄다면 이번 버전부터는 대화를 압축하고 계속 진행합니다.
  • --output-format json이나 stream-json 출력을 문자열 그대로 비교하는 스크립트가 있다면 제어 문자와 Unicode 서식 문자가 \uXXXX로 이스케이프되니 확인하세요. JSON으로 파싱한 값은 같습니다.
  • VS Code에서 텔레메트리를 꺼 두었다면 확장이 시작하는 Claude Code 세션도 사용 지표와 오류 보고를 보내지 않고 기능 플래그를 가져오지 않습니다.