Claude Code v2.1.309 업데이트: 개발 워크플로우 지원 향상

10월 23, 2026

글: MinoSui

Claude Code v2.1.309 버전이 출시되었습니다. 이번 업데이트는 스킬 관리, 데이터 시각화 기능, VS Code 개발 환경에서의 가시성을 개선하는 변경사항을 포함합니다. 주요 신규 기능과 사용 환경 개선 항목을 확인할 수 있습니다.

핵심 요약

스킬 이름 충돌 해결을 위한 폴더 네임스페이스 경로 지원 추가
데이터 시각화 스킬의 APCA 텍스트 대비 측정 표준 지원
VS Code 확장 프로그램의 프록시 TLS 인증서 경고 진단 로그 제공

릴리스 노트 전체
새로 쓸 수 있게 된 기능
내 환경에서 효과 재보기
업데이트 방법과 버전 확인

릴리스 노트 전체

공식 릴리스 노트에 적힌 79개 항목을 원래 순서를 지켜 한 줄에 한 항목씩 적었습니다. 원문에서 빼거나 원문에 없는 내용을 더한 항목은 없습니다.

macOS 및 Linux에서 샌드박스 처리된 Bash 명령이 매 명령 실행 전 샌드박스 외부에서 셸 시작 파일을 실행하던 문제를 고쳤습니다
패턴의 폴더가 심볼릭 링크를 통해 접근될 때 macOS 샌드박스의 `denyWrite` 글로브 패턴이 경로의 실제 위치에 적용되지 않던 문제를 고쳤습니다
샌드박스 처리된 명령과 자동 수락된 편집이 `--mcp-config`로 전달된 MCP 설정 파일을 수정할 수 있던 문제를 고쳤습니다
print 및 SDK 세션에서 비활성화된 MCP 서버가 이후의 권한 프롬프트로 인해 다시 연결되던 문제를 고쳤습니다
리디렉션 열기에 실패할 수 있는 명령으로 설정된 변수를 Bash 권한 검사가 신뢰하던 문제를 고쳤습니다
단순 `cd`와 달리 `cd`가 래핑되거나 접두사가 붙은 경우, git 실행 전 디렉터리를 변경하는 일부 복합 명령에 대해 Bash 권한 검사가 확인 메시지를 띄우지 않던 문제를 고쳤습니다
서브셸도 포함된 일부 명령에서 `Edit(path)` 거부 규칙이 해당 경로로의 Bash 리디렉션을 차단하지 못하던 문제를 고쳤습니다
작업 트리 격리 세션에서 격리 보호 기능이 거부해야 할 일부 로캘 접두사 명령을 허용하던 문제를 고쳤습니다
zsh의 작업 트리 격리 세션에서 격리 보호 기능이 거부해야 할 일부 산술 명령을 허용하던 문제를 고쳤습니다
Claude Code가 생성하는 작업 트리 및 브랜치 체크아웃이 다른 git 작업과 마찬가지로 git replace 참조를 무시하도록 고쳤습니다
설정 디렉터리가 심볼릭 링크를 통해 접근될 때 프로필 저장소 쓰기 보호가 적용되지 않던 문제를 고쳤습니다
매우 큰 중첩 CLAUDE.md 아래의 파일을 읽은 후 세션이 반복적으로 압축되던 문제를 고쳤으며, 크기 제한을 초과하는 중첩 CLAUDE.md는 이제 시작 부분만 로드합니다
응답이 시작되기 전에 ctrl+enter(지금 보내기)를 누르면 메시지가 큐에만 들어가고, 해당 훅이 실행 중일 때 누르면 메시지가 큐에 남아 있는 상태로 프롬프트 훅이 다시 시작되던 문제를 고쳤습니다
`!` 모드에서 키 바인딩된 슬래시 명령이 셸에서 실행되던 문제를 고쳤습니다
ctrl+o가 아직 전달 대기 중인 다른 에이전트 및 세션의 메시지를 표시하지 않던 문제를 고쳤으며, 이제 트랜스크립트 아래에 대기 중으로 표시되어 전체 내용이 나타납니다
긴 도구 출력 미리보기가 이모지 중간에서 잘려 `jq`로 파싱할 수 없는 세션 트랜스크립트가 남던 문제를 고쳤습니다
부모의 `/proc`을 공유하는 Linux 샌드박스에서 Read가 PDF 페이지 범위에 대해 "File does not exist"를 보고하던 문제를 고쳤습니다
Claude Desktop에서 호스팅되는 세션의 연결이 새로고침될 때 메시지가 간혹 유실되던 문제를 고쳤습니다
동일한 컴퓨터의 터미널이 다른 계정이나 조직에 로그인되어 있을 때 Claude 데스크톱 앱의 Claude Code 세션에서 기능이 누락되던 문제를 고쳤습니다
git 저장소가 아닌 폴더에 대해 `claude remote-control` 상태 표시줄이 브랜치를 `HEAD`로 표시하던 문제를 고쳤습니다
분할 창 에이전트 팀원이 리더의 명령줄에 지정된 도구 거부 및 `--tools` 규칙을 상속하지 않던 문제를 고쳤습니다
`/rename`으로 이름을 변경한 세션이 VS Code 창 다시 로드 또는 비대화형 `--resume` 이후 다른 세션에 자동 생성된 이름으로 나타나던 문제를 고쳤습니다
`/code-review --fix`, 하위 에이전트 또는 셸 명령을 통해 체크포인트된 파일이 변경된 턴에 대해 `/rewind` 목록에 "No code changes"가 표시되던 문제를 고쳤습니다
`/privacy-settings`에 오래된 "Help improve our AI models" 값이 표시되던 문제를 고쳤으며, 이제 설정을 가져올 수 없을 때도 안내합니다
조직에서 피드백을 수락하지 않을 때 피드백 기능이 "try again later"로 표시되던 문제를 고쳤으며, 이제 서버의 사유와 버그 신고 위치를 표시합니다
크기가 초과된 /feedback 보고서가 트랜스크립트 없이 재전송되지 않고 실패하던 문제를 고쳤습니다
다른 스킬이 이미 해당 이름을 차지하고 있을 때 `--add-dir` 폴더의 스킬에 접근할 수 없던 문제를 고쳤으며, 이제 `<folder>:<name>` 형태로 제공됩니다
셸에서 파일이 변경되었을 때 `/verify` 및 `/code-review`가 중첩된 패키지 자체의 스킬을 찾지 못하던 문제를 고쳤습니다
/claude-api 스킬에서 `ant beta:worker poll --on-work`가 명령에 추적 컨텍스트를 전달한다고 잘못 안내하던 문제를 고쳤습니다
/claude-api 스킬의 C# 추적 설정에서 클라우드 플랫폼 클라이언트의 스팬이 누락되던 문제를 고쳤습니다
/claude-api 스킬에서 AWS의 Claude Platform 요청에 대한 API 스팬이 호출자의 추적에 결합될 수 없다고 잘못 안내하던 문제를 고쳤습니다
PowerShell에서 실행되는 훅의 프로그램이 종료 코드 2로 종료될 때 차단되지 않던 문제와, Windows에서 Git for Windows가 설치되지 않았을 때 `"shell": "powershell"`이 지정된 `PreToolUse` 및 `PermissionRequest` 훅이 무조건 통과되던 문제를 고쳤습니다
`haiku`와 같은 별칭으로 모델을 지정하는 모드의 `turn.step` 훅이 모델 오류로 모든 요청에 실패하던 문제를 고쳐 이제 별칭이 해당 모델로 올바르게 확인됩니다
디스크 읽기 오류 발생 후 claude.ai에서 동기화된 플러그인과 스킬이 세션 도중에 제거되기도 하던 문제를 고쳤습니다
특정 축소 스크립트가 포함된 페이지나 Claude가 먼저 읽을 수 없었던 아티팩트 등 일부 일반 페이지에 대해 아티팩트 게시 및 업데이트가 거부되던 문제를 고쳤습니다
해당 턴에서 대화가 압축된 후 남은 턴 동안 매 아티팩트 업데이트마다 Claude가 권한을 요청하던 문제를 고쳤습니다
`ANTHROPIC_BEDROCK_BASE_URL`이 기본 `bedrock-runtime.<region>.amazonaws.com` 엔드포인트로 설정되어 있을 때 Amazon Bedrock에서 세분화된 도구 스트리밍이 꺼진 상태로 유지되던 문제를 고쳤습니다
연결 유지 핑만 보내는 게이트웨이 뒤에서 "Waiting for API response" 힌트가 깜빡이던 문제를 고쳤으며, Anthropic 백엔드 외의 경로는 이제 45초 동안 대기합니다
Claude가 PR, 이슈, 댓글에서 역할 이름과 플레이스홀더를 멘션으로 작성하여 무관한 GitHub 사용자에게 알림을 보내던 문제를 고쳤습니다
Linux: 백그라운드 명령이 세션보다 오래 유지될 때 샌드박스 쓰기 거부가 해제되던 문제를 고쳤습니다
Windows: 현재 디렉터리를 대상으로 하고 추가 인수가 포함된 일부 `Set-Location` 또는 `cd` 명령을 PowerShell 권한 검사가 자동 승인하던 문제를 고쳐 이제 승인을 요청합니다
macOS: Xcode나 Command Line Tools가 없는 Mac에서 Claude Code가 시작될 때마다 "Install Command Line Developer Tools" 대화상자가 열리던 문제를 고쳤습니다
자체 호스팅 러너: `/code-review`와 같은 첫 번째 프롬프트가 하위 에이전트에서 여전히 작동 중일 때 `--startup-timeout-min`이 세션을 중단시키던 문제를 고쳤으며, 멈춘 프로세스는 여전히 중단됩니다
Windows에서 Claude Code가 자체적으로 실행하는 여러 git 명령의 속도를 개선했으며, 모든 플랫폼에서 git이 다른 언어로 설정되어 있어도 해당 명령의 오류가 영어로 표시됩니다
훅 모듈이 너무 깊게 중첩되어 로드할 수 없을 때 발생하는 오류를 개선하여 단순 스택 오버플로 메시지 대신 파일 이름을 표시하도록 했습니다
디스크 여유 공간 부족 처리 방식을 개선하여, 디스크가 꽉 차 중단된 Bash 명령은 그 사실을 알리고 확보할 폴더를 안내하며 가득 찬 임시 볼륨에서 시작할 때는 원시 ENOSPC 오류 대신 명확한 메시지를 출력합니다
OpenTelemetry 추가를 요청받을 때 /claude-api 스킬이 SDK 추적과 함께 API 추적도 제안하도록 개선했습니다
기능이 지원되지 않는다고 안내하기 전에 /claude-api 스킬이 최신 실시간 문서를 확인하도록 개선했습니다
자체 호스팅 러너: 새 러너로 이동하는 세션을 개선하여 Claude가 중단된 도구 호출을 결과 불명으로 표시된 상태로 인식하도록 했습니다
번들된 dataviz 스킬을 업데이트하여 텍스트 대비 측정 기준으로 APCA를 허용하고(AA 준수가 필요한 곳에서는 WCAG 2 비율 유지), 팔레트 검증기 스크립트에 `apca(text, background)` 함수를 추가하며, 색상이 채워진 차트 내부의 레이블이 흰색이어야 하는지 거의 검은색이어야 하는지 안내하도록 했습니다
/claude-api 스킬을 업데이트하여 서비스 계정 키와 Workload Identity Federation 토큰으로 OpenTelemetry 대상을 관리할 수 있도록 했습니다
`sed -i`가 파일 편집 시뮬레이션 미리보기가 아닌 표준 Bash 프롬프트를 받아 작성된 그대로 실행되도록 변경했으며, 다른 Bash 편집과 마찬가지로 더 이상 `/rewind`로 복원되지 않습니다
`claude ultrareview`가 워크스페이스 신뢰를 요구하도록 변경하여 터미널에서는 확인을 요청하고 그렇지 않으면 거부하며, 스크립트에서는 값을 받지 않는 `--trust-workspace`를 전달하거나(앞에 PR 번호 또는 베이스 브랜치 배치) `CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1`을 설정해야 합니다
데스크톱 앱 및 VS Code의 권한 우회 모드에서 위험한 `rm` 및 `rmdir` 프롬프트가 재작성 힌트와 함께 명령을 즉시 거부하도록 변경하여 무인 세션이 계속 진행되도록 했습니다
설정에서 샌드박스 제외 대상으로 지정된 명령이 샌드박스가 활성화되었지만 실행할 수 없는 상태일 때 쓰기 목록 경로에 쓰기 전 확인하도록 변경했으며, 이때 비샌드박스 대체 실행은 거부됩니다
일반 클론 및 Bash 샌드박스가 설정된 부분 클론에서 git이 작업 트리 생성 및 재사용 시 더 이상 온디맨드로 객체를 가져오지 않도록 변경했으며, 이러한 부분 클론은 객체를 먼저 가져옵니다
`/claude-api` 스킬이 Managed Agents 하위 에이전트 팀을 `coordinator` 대신 동적 워크플로가 기본으로 활성화된 `multiagent_20261001` 기반으로 구축하도록 변경했습니다
[VSCode] TLS 검사 프록시 환경 등에서 받아쓰기나 확장 프로그램 자체의 요청이 인증서 검증에 실패할 때의 조치 방법을 알려주는 로그 경고를 추가했습니다
[VSCode] 에디터가 파일의 불완전한 복사본을 캐시한 후 Claude 패널이 빈 상태로 유지되던 문제를 고쳐 이제 자체적으로 복구되거나 무엇이 잘못되었고 어떻게 해결해야 하는지 표시합니다
[VSCode] 메시지를 보내지 않고 새 세션을 시작할 때마다 세션 기록이 비어 있는 "Untitled" 세션으로 채워지던 문제를 고쳤습니다
[VSCode] `/goal`과 같은 긴 슬래시 명령 메시지가 채팅 패널을 가득 채우던 문제를 고쳤습니다. 이제 다른 프롬프트처럼 '더 보기' 뒤로 접힙니다 (anthropics/claude-code#97469)
[VSCode] 채팅 패널 너비를 좁힌 후 긴 메시지가 '더 보기' 뒤로 접히지 않던 문제를 고쳤습니다
[VSCode] 채팅 입력창에서 Ctrl+J가 항상 줄바꿈을 삽입하던 문제를 고쳤습니다. 이제 ~/.claude/keybindings.json의 Chat 컨텍스트에서 "ctrl+j"를 null로 설정하면 VS Code와 운영체제에 처리를 맡깁니다
[VSCode] 프롬프트 위에 표시되는 모드의 "From the … plugin" 라벨이 슬래시 명령 및 @-멘션 메뉴 위로 겹쳐 그려지던 문제를 고쳤습니다 (anthropics/claude-code#102981)
[VSCode] 복사한 LaTeX 수식을 붙여넣을 때 빈 목록 항목, 문단 또는 코드 블록이 생기거나 목록 항목 번호가 1부터 다시 매겨지던 문제를 고쳤습니다
[VSCode] 조직에서 피드백을 수락하지 않을 때 피드백 오류에 HTTP 상태 코드만 표시되던 문제를 고쳤습니다
[VSCode] 채팅 패널의 Edit 및 Write 속도를 개선했습니다. 각 편집 후 새로운 문제를 기다리는 시간이 기존 1~1.5초에서 대부분 0.75초로 단축되었습니다
[Cloud sessions] 루틴 양식의 '커넥터 추가' 목록이 로딩 중일 때 사용 가능한 커넥터가 없다고 표시되던 문제를 고쳤습니다
[Cloud sessions] 클라우드 환경 편집기에서 환경 변수 순서가 뒤섞이고 두 종류의 따옴표가 모두 포함된 값에 백슬래시가 추가되던 문제를 고쳤습니다
[Cloud sessions] 관리자 설정의 자체 호스팅 환경 세부 정보 대화 상자에서 본문만 스크롤되고 제목, 탭, 버튼은 그대로 보이도록 고쳤습니다
[Cloud sessions] 클라우드 세션에서 읽기 쉬운 페이지 대신 이스케이프된 JSON을 표시하던 "read documentation" 도구 행을 고쳤습니다
[Cloud sessions] 클라우드 세션의 변경 사항 창을 개선하여 푸시된 커밋만 표시되는지, 아니면 Claude의 편집 내용만 표시되는지 명시하도록 했습니다
[Claude Tag] Slack의 Claude가 채널용으로 승인한 초안을 실수로 DM에 게시하던 문제를 고쳤습니다. 이제 채널이 지정되지 않은 게시물은 거부되어 승인된 채널로 전송됩니다
[Claude Tag] 세션이 중지되었을 때 Slack의 Claude 승인 카드에서 '허용' 및 '거부'를 눌러도 아무 동작도 하지 않던 문제를 고쳤습니다. 이제 응답하면 세션이 다시 시작됩니다
[Claude Tag] 워크스페이스가 다른 Claude 조직으로 이전된 후, Enterprise Grid의 공유되지 않은 채널을 포함하여 Slack 채널에서 Claude가 태그되지 않은 메시지를 무시하던 문제를 고쳤습니다
[Claude Tag] Slack 채널의 Claude가 다른 사용자가 해당 스레드에 방금 추가한 최신 메시지를 읽기 전에 스레드 답글을 먼저 게시하던 문제를 고쳤습니다
[Claude Tag] Claude Tag 관리자 설정의 Slack 페이지에서 목록 로드에 실패했을 때 연결된 워크스페이스가 없다고 표시되던 문제를 고쳤습니다. 이제 '다시 시도' 버튼이 포함된 오류를 표시합니다
[Code Review] 앞선 생성 시도가 실패했을 때 완료된 검토의 풀 리퀘스트에 체크 표시가 나타나지 않던 문제를 고쳤습니다. 이제 마지막 재시도를 통해 완료된 체크를 추가합니다
[Code Review] 실행 중인 검토 뒤로 대기 중이던 푸시가 `@claude review stop` 이후에도 여전히 검토를 시작하던 문제를 고쳤습니다. 이제 해당 체크가 닫히며 그 이유를 표시합니다

함께 읽기: Claude Code v2.1.308 업데이트 안정성 개선 사항 · Claude Code v2.1.307 업데이트: API 버전 관리 및 모니터링 강화 · Claude Code v2.1.306 릴리스 노트 분석

▲ 맨 위로

새로 쓸 수 있게 된 기능

이번 업데이트로 새로 쓸 수 있게 된 기능은 3가지입니다. 근거 항목은 위 릴리스 노트의 번호입니다.

기능	달라진 점	근거 항목
스킬 네임스페이스 경로 지원	추가 디렉토리(--add-dir) 내의 스킬 이름이 기존 스킬과 충돌할 때 <folder>:<name> 형태로 지정하여 접근할 수 있습니다.	27번
데이터 시각화 스킬 APCA 지원	기본 번들 데이터 시각화 스킬이 APCA 텍스트 대비 공식을 지원하여 차트 내 라벨의 대비 색상을 정확하게 산출합니다.	50번
VS Code TLS 인증서 검증 경고 로그	프록시 환경에서 음성 입력이나 확장 프로그램 요청이 실패할 때 문제 원인과 조치 방법을 알려주는 로그 경고를 출력합니다.	58번

▲ 맨 위로

내 환경에서 효과 재보기

에이전트, 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.309 이상이 필요합니다. 터미널에서 claude update로 새 버전을 받고, claude --version으로 2.1.309 이상인지 확인합니다.

claude update
claude --version

▲ 맨 위로

글쓴이 MinoSui · 블로그 운영자·편집 책임

편집 방침. 오류 제보는 문의로 받습니다. 글쓴이·블로그 소개

출처

Claude Code v2.1.309 릴리스 노트 · github.com

#IT·AI#클로드AI#ClaudeCode

작성일 2026-10-23 09:20

이 블로그 검색

미노쓰의 글log