이 글에서 알 수 있는 것:
allow_large 옵션으로 파일을 통째로 읽을 수 있게 된 배경과 사용법
- 비 UTF-8 파일(Shift-JIS・Windows-1252・GBK)의 오기재변환 버그가 수정된 경위
- 529 (Overloaded) 재시도의 최대 대기 시간을 환경 변수로 제어 가능하게 된 점
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS
2026년 10월 10일 아침(일본 시간), Claude Code v2.1.296이 출시되었다.
v2.1.295 다음 날 바로 다음 버전이라, 솔직히 따라가기는 어렵다. 하지만 이번에는 '기능 추가 6건 + 버그 수정 40건 이상'이라는 내용으로, 일본어 환경에서 사용하는 사용자에게 직접적인 영향을 주는 수정이 포함되어 있다. 릴리스 노트를 읽고 핵심 포인트를 정리했다.
출처: Claude Code v2.1.296 릴리스 노트 (2026-10-10 04:28 JST 공개)
릴리스 노트의 기술:
Added an allow_large option to the Read tool so Claude can read a text file
past the usual size limits in one call when it needs the whole file
and the context has room
Claude Code의 Read 툴에는 통상적인 크기 제한이 있다. 큰 파일은 offset / limit으로 분할하여 읽어야 했으며, '어디에 무엇이 쓰여 있는지 모르는 파일을 통째로 전달하고 싶다'는 상황에서는 번거로운 과정이 있었다.
allow_large: true를 지정하면 컨텍스트에 여유가 있을 경우 한 번에 파일 전체를 불러올 수 있다.
실제 자동화 스크립트를 Claude Code에 분석시키면서, 수백 줄짜리 설정 파일이나 CSV 파일을 '우선 어떤 구조인지 확인해 줬으면 좋겠다'는 용도로 사용했을 때는 분할 읽기를 했다. 이번 변경으로 '통째로 봐줘'라는 프롬프트를 작성하기가 쉬워졌다.
다만 조건은 '컨텍스트에 여유가 있는 경우'이므로, 긴 대화의 후반부나 다른 파일을 많이 읽은 후에는 기존과 다르지 않을 수 있다.
이는 일본어 환경 사용자에게 중요한 수정이다.
릴리스 노트의 기술:
Fixed Edit and NotebookEdit replacing every non-ASCII character
in files that are not valid UTF-8 (Windows-1252, Shift-JIS, GBK);
such edits are now refused
무슨 일이 일어나고 있었나: Edit이나 NotebookEdit 툴이 Shift-JIS와 같은 비 UTF-8 파일에 대해 처리를 수행할 경우, 모든 비 ASCII 문자(즉, 일본어 문자)가 깨지면서 덮어쓰여지는 문제가 있었다.
수정된 동작: 비 UTF-8 파일에 대한 편집은 refused(거부)된다. 데이터가 손상되는 것보다는 거절되는 것이 낫다.
국내 기업의 업무 시스템에서는 아직도 Shift-JIS 파일이 남아있는 경우가 있다. CSV 출력, 양식 정의 파일, 레거시 시스템과의 인터페이스 등, Shift-JIS가 들어오는 상황은 드물지 않다. v2.1.295까지 버전에서 이러한 파일을 Claude Code에 전달하여 편집하게 했다면, 의도치 않게 데이터가 손상되었을 가능성이 있다.
대처 방법으로는:
- UTF-8로 변환한 후 전달하기 (
nkf나 iconv로 변환)
- Claude Code에게 직접 편집시키지 않고, 변환 스크립트를 작성하게 하기
# Shift-JIS → UTF-8로 변환한 후 전달
nkf -w --overwrite file.csv
릴리스 노트의 기술:
Added CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS environment variable
to set a longer maximum delay for the backoff when retrying an overloaded (529) request
Claude가 과부하(529)를 반환했을 때, Claude Code는 백오프하여 재시도한다. 지금까지 백오프의 '최대 대기 시간'을 외부에서 설정할 수 있는 수단이 없었다.
야간 무인 실행 파이프라인에서 이것이 곤란한 상황을 비교해 보면:
| 상황 | 문제 |
|---|
| 529가 계속되어 재시도가 너무 짧음 | API 서버에 부하를 계속 주게 됨 |
| 처리가 민감하지 않은 시간대에 작동함 | 백오프(Backoff)가 너무 길어서 타임아웃보다 먼저 해소될 가능성이 있음 |
# 최대 5분 (300,000ms) 대기 설정 예시
export CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=300000
야간에 자동 실행하는 시스템에서는 Claude의 이용 한도에 도달했을 때의 재시도 동작이 운영 안정성과 직결됩니다. 이 변수를 통해 파이프라인의 성격에 맞게 조정할 수 있게 되었습니다.
릴리스 노트 설명:
Added autoCompactWindow to subagent frontmatter and --agents definitions,
so a subagent can auto-compact earlier than the main conversation's window
여러 서브 에이전트를 병렬로 실행할 경우, 각각 고유의 컨텍스트 윈도우를 가집니다. 이전에는 '서브 에이전트가 일찍 컨텍스트를 압축하고 싶다'는 제어가 불가능했습니다.
autoCompactWindow를 서브 에이전트 정의에 넣으면, 메인 대화보다 빠른 타이밍에 컨텍스트 압축을 실행할 수 있습니다. 긴 처리를 서브 에이전트에 병렬로 맡길 때, 컨텍스트 상한에 도달하기 전에 대처할 수 있게 되었습니다.
릴리스 노트 설명:
Added CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL to run every workflow agent on one model
while other subagents keep theirs
일반 서브 에이전트와 워크플로우 에이전트를 구분하여 사용하는 경우, 워크플로우 에이전트만 별도의 모델에 고정할 수 있게 되었습니다.
# 워크플로우 에이전트만 Haiku로 설정
export CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL=claude-haiku-4-5-20251001
메인 에이전트는 Sonnet을 사용하면서, 라우팅 등 판단이 가벼운 워크플로우 에이전트는 Haiku로 구동하는 비용 최적화가 가능합니다.
릴리스 노트 설명:
Fixed managed-settings PreToolUse hooks that deny a tool call with "continue": false,
and managed prompt hooks that block one, refusing the call but not ending the turn
managed-settings(조직/엔터프라이즈 설정)에서 PreToolUse hook을 설정하여 도구 호출을 `
| 변경 | 개요 | 특히 관련된 사용자 |
|---|
allow_large | 한 번에 큰 파일을 읽을 수 있는 옵션 | 파일 분석을 자주 하는 사용자 |
| Shift-JIS 오기재변환 버그 수정 | 비(非) UTF-8 파일에 대한 편집을 거부(refuse)로 변경 | 국내 기업 및 일본어 환경의 사용자 |
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS | 529 재시도의 최대 대기 시간을 환경 변수로 제어 | 야간 무인 실행을 하는 사용자 |
autoCompactWindow | 서브 에이전트가 컨텍스트 압축을 일찍 수행 | 서브 에이전트를 많이 사용하는 사용자 |
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL | 워크플로우 에이전트의 모델을 개별 지정 | 비용 최적화를 목표로 하는 사용자 |
| managed-settings hooks 버그 수정 | ` | |
