Claude Code v2.1.305 업데이트 주요 변경 사항 정리
Claude Code v2.1.305 릴리스가 배포되었습니다. 이번 버전에는 리눅스 컨테이너 환경을 위한 샌드박스 설정과 재시도 대기 시간 제어 옵션이 추가되었습니다. 터미널 및 VS Code 확장 프로그램의 진단 편의 기능도 함께 개선되었습니다.
- 리눅스 샌드박스에서 사용자 네임스페이스 생성을 허용하는 옵션이 추가되었습니다.
- 무인 재시도 모드에서 사용량 제한 해제를 주기적으로 감지하는 간격 설정이 도입되었습니다.
- /usage 화면에서 경고 원인을 확인하고 키 하나로 자동 조치할 수 있습니다.
- VS Code 확장 프로그램에 시작 훅 실행 상태 스피너와 음성 안내가 지원됩니다.
이번 릴리스의 변경 내역
공식 릴리스 노트의 38개 항목을 원문 순서대로 한 줄씩 옮겼습니다. 더하거나 뺀 항목은 없습니다.
- Linux의 샌드박스 처리된 명령어가 사용자 네임스페이스를 생성할 수 있도록 `sandbox.allowNestedUserNamespaces`를 추가했습니다(Chromium, 루트리스 podman). 이를 통해 샌드박스의 파일 보호를 우회할 수 있습니다.
- 무인 재시도 모드(`CLAUDE_CODE_RETRY_WATCHDOG`)가 재설정 시간 전에 해제된 사용량 한도를 감지하도록 `CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS`를 추가했습니다.
- 엔드포인트나 게이트웨이가 도구 검색을 거부할 때 Vertex, Bedrock 및 기타 제공자에서 모든 요청이 실패하고, ToolSearch가 허용되지 않거나 `--tools`에서 누락된 게이트웨이 뒤에서 실패하던 문제(2.1.304 회귀)를 고쳤습니다. 이제 Claude Code가 도구 검색 없이 재시도합니다.
- 모델 이름이 대소문자나 `[1m]` 태그로 인해 `modelOverrides` 값과 다를 때 `/effort` 및 `/autocompact` 설정이 적용되지 않던 문제를 고쳤습니다.
- 베어 저장소의 새 워크트리가 기본 브랜치 대신 로컬 HEAD에서 시작되거나 변경되지 않은 서브에이전트 워크트리가 정리되지 않던 문제를 고쳤습니다.
- 디스크가 가득 찼을 때 Bash 명령어가 원시 `ENOSPC` 파일 경로와 함께 실패하던 문제를 고쳤습니다. 이제 디스크가 가득 찼으며 아무것도 실행되지 않았다는 오류 메시지가 표시됩니다.
- 클라우드 세션이나 SDK의 `setMcpServers`로 전달된 MCP 서버가 세션 도중 사용자의 설정에 있는 동일한 이름의 서버로 교체되던 문제를 고쳤습니다.
- 서브에이전트가 폴백 모델로 전환한 후 Claude가 서브에이전트의 작업에 대해 잘못된 모델 이름을 지정하던 문제를 고쳤습니다.
- 압축 과정에서 크기를 맞추기 위해 요약에서 가장 오래된 메시지를 제외해야 할 때 클라우드 세션과 팀원이 Claude에게 이를 알리지 않던 문제를 고쳤습니다.
- 예약된 Cowork 클라우드 세션에서 승인해 줄 사람이 없는 상황임에도 WebFetch에 URL 승인이 필요한 각 서브에이전트를 5분 동안 기다리던 사례들을 추가로 고쳤습니다.
- 워크플로 재개 시 실행 기록 저널에서 결과를 가져오는 대신 이미 완료된 `pipeline()` 및 `parallel()` 에이전트를 다시 실행하던 문제를 고쳤습니다.
- Remote Control에서 `/resume`으로 대화를 전환한 후 `/resume`에 빈 "(session)" 항목이 남던 문제를 고쳤습니다.
- 폭이 좁은 터미널에서 `/usage` 행이 잘리던 문제를 고쳤습니다.
- 시작 경고가 로고 위에 원시 텍스트로 출력되던 문제를 고쳤습니다. 이제 디버그 로그로 전송되며, 아무것도 제한하지 않는 권한 규칙은 배너 아래에 경고 행으로 표시됩니다.
- 화면 판독기 모드를 고쳤습니다. 검색 상자에 VoiceOver가 "전화 녹음기"로 읽던 기호 대신 "Search:"가 표시되며, Ctrl+R 검색 일치 항목 및 "ultrathink"와 같은 강조된 프롬프트 텍스트의 단어 내부에 공백이 생기지 않습니다.
- 자체 호스팅 러너: `TERM`이 설정되었을 때 러너나 오케스트레이터와 stdout만 공유하는 시작 스크립트가 `Resource temporarily unavailable` 오류와 함께 실패하던 문제(2.1.300 회귀)를 고쳤습니다.
- 자체 호스팅 러너: git 자격 증명 도우미나 askpass 프로그램이 `GIT_CONFIG`를 통해 설정을 읽을 때 2.1.296부터 저장소 접근에 실패하던 문제를 고쳤습니다.
- 자체 호스팅 러너: 백그라운드에서 시작된 러너가 출력을 열린 상태로 유지할 때 오케스트레이터가 spawn-runner 훅을 시간 초과로 보고하던 문제를 고쳤습니다.
- `/usage`를 개선했습니다. 이제 각 경고에 출처를 명시하는 한 줄 해결 방법이 표시되며 `f`를 눌러 해결 방법을 적용할 수 있습니다. 동일한 해결 방법이 VS Code와 `/doctor`에도 표시됩니다.
- 프롬프트 입력용 Enter 키가 수락으로 인식될 가능성을 줄이도록 MCP 동의 대화 상자를 개선했습니다.
- iTerm2 3.5 이상에서 모드의 `Image`가 `alt` 텍스트만 표시하던 전체 화면 렌더링 시 그림을 정상적으로 그리도록 개선했습니다.
- Remote Control: 생성 모드 메시지를 개선했습니다. 이제 `w`를 누르면 해당 폴더에 새 모드가 저장되었다고 표시되며, 이후 저장된 모드를 사용하는 `claude remote-control` 시작 시 출처가 어디인지 안내합니다.
- `env`에서만 `${VAR}`를 사용하는 `managed-mcp.json` stdio 서버의 필터링을 중단하도록 `allowedMcpServers`를 변경했습니다. 허용 목록에서 제외되었던 서버가 업그레이드 시 로드되므로, 비활성 상태를 유지하려면 `deniedMcpServers`를 사용하세요.
- 조직의 관리형 설정에서 `allowManagedPermissionRulesOnly`를 설정한 경우 Claude Desktop이 경로로 마운트한 플러그인이 더 이상 `allowed-tools`를 유지하지 않도록 변경했습니다.
- `/artifacts` 삭제 확인 시 유지하려면 1 또는 Enter, 삭제하려면 2, 취소하려면 Esc를 입력받도록 변경했습니다. 더 이상 `y`와 `n`으로 응답할 수 없습니다.
- 모드의 고정 창이 더 넓은 터미널에서 유지된 너비를 포함하여 터미널 너비의 45% 이내로 유지되도록 변경했습니다.
- [VSCode] SessionStart 또는 Setup 훅이 실행되는 동안 화면 판독기 알림과 함께 "Running start-up hooks" 스피너 상태를 추가했습니다.
- [VSCode] 사용자의 `spinnerVerbs` 설정이 내장 동사를 짧은 동사로 대체할 때 스피너가 "Compacting..."을 잘라내던 문제를 고쳤습니다.
- [VSCode] 세션이 제시간에 시작되지 않고 실행 중인 훅이 없을 때 표시되는 메시지를 변경했습니다. 이제 로그인과 네트워크를 먼저 안내하는 대신 출력 로그를 먼저 표시하고 원인 목록을 나열합니다.
- [Cloud sessions] Cloud 환경 관리자 페이지에서 기존 환경 저장을 "installs packages" 오류와 함께 잘못 거부하던 문제를 고쳤습니다.
- [Cloud sessions] 자체 호스팅 환경 삭제 시 대화 상자와 오류 메시지에 삭제를 차단하는 요소와 삭제가 영향을 미칠 대상을 표시하도록 개선했습니다.
- [Claude Tag] Claude가 참여하지 않은 공개 Slack 채널을 Claude Tag 관리자 장소 추가 검색에 추가하여 관리자가 해당 위치에서 설정할 수 있도록 했습니다.
- [Claude Tag] 다른 GitHub 계정으로 이전된 저장소를 다시 추가할 수 있도록 Claude Tag 접근 번들을 고쳤습니다.
- [Claude Tag] Slack DM 스레드에 설정된 루틴이 해당 스레드의 다른 루틴으로 대화가 다시 시작된 후 더 이상 메시지를 게시하지 않던 문제를 고쳤습니다. 이제 두 루틴 모두 계속 게시됩니다.
- [Claude Tag] Slack 스레드에 설정된 루틴이 대화가 끝난 후 메시지를 게시하지 않고도 성공으로 보고하던 문제를 고쳤습니다. 해당 실행은 이제 건너뛰고 생성자에게 알립니다.
- [Claude Tag] 대규모 조직의 Claude Tag 관리자 페이지를 개선하여 채널 목록을 로드하는 동안에도 플러그인, 스킬, 번들 편집이 가능하도록 했습니다.
- [Code Review] 리뷰 도중 풀 리퀘스트에 여러 번 푸시가 발생했을 때 Code Review가 최신 커밋을 검토하지 못하던 문제를 고쳤습니다.
- [Code Review] 이전의 차단성 발견 사항이 아직 열려 있는 동안에는 Code Review 재검토가 더 이상 LGTM으로 시작되지 않도록 변경했습니다.
함께 읽기: Claude Code v2.1.304 업데이트: 새 명령어와 모드 제어 기능 추가 · Claude Code v2.1.303 릴리스: 버그 수정과 안정성 개선 · Claude Code v2.1.302 변경 사항: 유휴 압축 설정과 서브에이전트 기본값
추가된 기능 정리
이번 업데이트로 새로 쓸 수 있게 된 기능은 5가지입니다. 근거 항목은 위 릴리스 노트의 번호입니다.
| 기능 | 달라진 점 | 근거 항목 |
|---|---|---|
| 리눅스 샌드박스 중첩 사용자 네임스페이스 허용 | sandbox.allowNestedUserNamespaces 설정을 활성화하여 리눅스 샌드박스 내부 명령어가 사용자 네임스페이스를 생성하도록 지원합니다. | 1번 |
| 무인 재시도 모드 사용량 한도 재확인 간격 설정 | CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS 환경 변수를 통해 재설정 시각 이전에 한도가 해제된 경우를 감지하는 주기를 밀리초 단위로 지정할 수 있습니다. | 2번 |
| /usage 단축 수정 기능 | /usage 명령 실행 시 각 경고의 원인을 한 줄로 표시하며 f 키 입력으로 즉시 권장 조치를 적용합니다. | 19번 |
| VS Code 시작 훅 실행 상태 표시 | SessionStart 또는 Setup 훅이 동작하는 동안 상태 표시줄 스피너와 스크린 리더 안내로 진행 상황을 전달합니다. | 27번 |
| Claude Tag 미참여 공개 채널 검색 | 관리자 화면의 위치 추가 검색에서 Claude가 아직 들어가지 않은 공개 슬랙 채널을 찾아 등록할 수 있습니다. | 32번 |
업데이트 효과 직접 재보기
에이전트, effort, 속도, 재시도에 관한 변경이 내 작업에서 얼마나 차이 나는지는 직접 재 보면 숫자로 확인됩니다. claude -p를 JSON 출력으로 실행하면 걸린 시간과 턴 수, 서브에이전트 결과가 함께 나옵니다.
claude -p "<작업 지시>" \
--output-format json < /dev/null
작업 지시는 옵션보다 앞에 둡니다. --allowedTools Agent "<작업 지시>"처럼 쓰면 --allowedTools가 값을 여러 개 받는 옵션이라 작업 지시까지 도구 이름으로 읽습니다. 옵션을 뒤에 쓰려면 --allowedTools=Agent처럼 =로 붙입니다. 아무것도 보내지 않는 파이프에 표준 입력이 연결돼 있으면 3초를 기다린 뒤 경고를 띄우고 진행하는데, < /dev/null로 표준 입력을 막아 두면 이 대기가 없습니다.
- duration_ms: 실행 전체에 걸린 시간(밀리초)
- num_turns: 결과가 나오기까지 걸린 턴 수
- subagent_stats.completed / subagent_stats.failed: 서브에이전트가 끝까지 마친 수와 실패한 수
단순 조회 작업 하나(예: 어떤 함수가 어디서 호출되는지 찾기)와 코드 수정 작업 하나(예: 함수 하나에 테스트 추가)를 정해 둡니다. 같은 저장소에서 설정마다(업데이트 전후, effort 수준별) 두 작업을 각각 여러 번 실행하고, 조회와 수정의 기록을 따로 모아 비교합니다.
아래는 Claude Code 2.1.292에서 서브에이전트 한 개를 띄운 실행의 실제 출력에서 위 네 값만 남긴 것입니다. 나머지 키는 ...로 줄였습니다.
{
"duration_ms": 14271,
"num_turns": 4,
"subagent_stats": {
"completed": 1,
"failed": 0,
...
},
...
}
기록표의 첫 줄은 이 실행을 옮긴 것입니다. 조회 작업과 코드 수정 작업을 나눠, 실행할 때마다 한 줄씩 더합니다.
| 작업 | 설정 | 시간(ms) | 턴 | 완료/실패 |
|---|---|---|---|---|
| 예시 | 2.1.292 | 14271 | 4 | 1 / 0 |
업데이트 방법과 버전 확인
이 글의 변경을 모두 쓰려면 Claude Code 2.1.305 이상이 필요합니다. 터미널에서 claude update로 새 버전을 받고, claude --version으로 2.1.305 이상인지 확인합니다.
claude update
claude --version
- Claude Code v2.1.305 릴리스 노트 · github.com
작성일 2026-10-21 06:19
소개 · 문의 · 개인정보처리방침 · 면책 안내 · 저작권 안내 · AI, IT 글 모음
© 2026 MinoSui. 이 글의 무단 전재·재배포를 금합니다. 원문: https://minoss0918.blogspot.com/
댓글
댓글 쓰기