심야 시간에 자동 실행 로그를 아침에 확인했을 때, 'Usage credits required for 1M context' 메시지를 남기고 세션이 멈춰 있었습니다.
200K 토큰을 초과하는 처리가 표준 컨텍스트(standard context)에서는 1M의 컨텍스트가 필요하다고 판단되어 강제 종료되고 있었습니다.
v2.1.311에서 이 동작 방식이 변경되었습니다. 더 이상 200K를 초과할 때 멈추는 것이 아니라, 대화 내용을 자동으로 압축하여 계속 진행하게 되었습니다.
릴리스 노트에는 'Fixed standard-context sessions stopping with 'Usage credits required for 1M context' when a request ran over 200K tokens; Claude Code now compacts the conversation and continues'라고 명시되어 있습니다.
이 수정 사항 하나만으로도 심야 시간에 무인(unmanned)으로 Claude Code를 구동하는 팀에게는 큰 의미가 있습니다.
본 기사에서 알 수 있는 내용:
- v2.1.311에서의 1M 컨텍스트 오류 동작 변경
- CLAUDE.md의 목록 길이가 구동 시간에 영향을 주던 문제 경위
- MCP 및 서브 에이전트(sub-agent) 계열에서 어떤 동작이 바뀌었는지
- 무인 실행/스케줄 실행과 관련된 수정 개요
대상은 Claude Code를 서브 에이전트, MCP 연동, SDK/claude -p로 사용하는 엔지니어입니다.
v2.1.311의 릴리스 노트에는 40가지가 넘는 수정 사항이 포함되어 있습니다.
모든 내용을 나열하기보다는 '기업 업무 활용 및 자동화 환경에서의 무인 실행'이라는 관점에서 선별한 10가지에 집중하여 정리했습니다.
'CLAUDE.md에 긴 목록 항목을 넣으면, 구동 후와 파일 편집 후에 긴 정지(freeze)가 발생하던 문제'를 수정했습니다.
(Fixed long freezes at startup and after reading or editing files when a CLAUDE.md file holds a very long list item)
대규모 프로젝트에서는 CLAUDE.md에 설정, 금지 사항, 페르소나 정의 등 대량의 목록을 넣는 경우가 많습니다.
이것이 수십 줄에서 수백 줄에 이르기까지 길어지면, 구동할 때마다 그리고 큰 파일을 읽고 쓸 때마다 몇 초간 멈추는 현상이 발생했습니다.
대처 방법으로는 CLAUDE.md의 목록 항목을 짧게 하거나, 항목 수를 줄이거나, 별도의 파일로 참조하는 것이 효과적입니다.
'CLAUDE.md 요약 파일(CLAUDE-summary.md)을 따로 만들고 본문 로딩량을 줄이는' 구성은 이 수정 사항과 결합될 경우 구동 속도에 도움이 됩니다.
또한 'Improved startup time for Pro and Max accounts by skipping two network requests on launches within an hour of the last check'라는 개선 사항도 있습니다.
Pro/Max 계정의 경우, 1시간 이내에 구동된 적이 있다면 확인용 네트워크 요청 2건을 건너뛰게 되었습니다.
매시(hourly) 또는 매일 여러 번 구동하는 운영 환경에서는 이 개선 효과가 누적됩니다.
앞서 언급했듯이, v2.1.311에서는 '200K 초과 시 정지'에서 '압축하여 계속 진행'으로 변경되었습니다.
기업에서의 대규모 처리—수백 개의 파일을 일괄 검토하는 경우, 큰 코드베이스를 가로질러 수정하는 경우, 긴 설계 문서를 기반으로 여러 수정을 연속적으로 실행하는 경우—에는 한 턴(turn) 만에 200K 토큰을 초과하는 것이 드물지 않습니다.
기존에는 그 지점에서 강제 종료되어 다음 날 아침에 '도중에 멈춰 있었다'는 로그를 확인할 수밖에 없었습니다.
v2.1.311 이후부터는 압축되면서도 계속 진행하기 때문에, 처리 도중의 정지가 발생할 가능성이 줄어듭니다.
주의: 압축 과정에서 과거 대화 내용 일부가 손실될 가능성이 있습니다.
긴 처리를 할 때는 중요한 중간 상태를 명시적인 파일에 기록하여 보존하는 설계 방식이 여전히 유효합니다.
압축된 후 Claude 측이 '이 작업을 통해 무엇을 했는지'를 정확하게 파악할 수 있는지는 작업의 성격에 따라 다릅니다.
수정 1: 연결 후 MCP 서버의 도구가 사용되지 않던 문제
'서브 에이전트가 시작된 후에 연결을 완료하는 MCP 서버의 도구를 서브 에이전트가 사용할 수 없었던' 문제가 수정되었습니다.
(Fixed subagents being unable to use MCP tools from servers that finish connecting after the subagent starts)
MCP 서버 중에는 연결에 시간이 걸리는 경우가 있습니다.
연결 완료 전에 서브 에이전트(sub-agent)가 시작될 경우, 해당 서버의 도구를 사용할 수 없는 상태로 처리가 진행되곤 했습니다.
v2.1.311부터는 연결 완료 후의 서버 도구도 활용할 수 있게 되었습니다.
여러 MCP 서버를 사용하는 플로우에서 특정 서버의 도구만 사용하지 못하는 문제가 발생했던 경우, 이번 수정으로 해결될 가능성이 있습니다.
수정 2: 워크트리가 오삭제되는 문제
'서브 에이전트가 시작한 백그라운드 서브 에이전트가 아직 워크트리(worktree)에서 작업 중인데, 부모 서브 에이전트의 격리된(isolated) 워크트리가 삭제되는' 문제가 수정되었습니다.
(Fixed a subagent's isolated worktree being removed while a background subagent it started was still working in it)
서브 에이전트를 병렬로 구동하는 환경에서는 이 문제가 데이터 손실이나 예상치 못한 오류로 이어지곤 했습니다.
병렬 서브 에이전트를 프로덕션(production) 환경에서 사용하던 팀은 이 버그를 겪었을 수 있습니다.
수정 3: /code-review가 두 번 실행되는 문제
'종료된 /code-review 또는 서브 에이전트에서 작동하는 스킬(skill)이 클라우드 세션이나 백그라운드 세션 재시작 시 두 번째 실행을 시작하던' 문제가 수정되었습니다.
(Fixed a finished /code-review, or another skill that runs in a sub-agent, running a second time when a cloud or background session restarts)
코드 리뷰의 중복 실행은 결과의 일관성(consistency)과 실행 비용 양쪽에 영향을 미칩니다.
수정 4: 충돌 후 세션 재시작
'턴(turn) 사이에 충돌한 백그라운드 세션이 첨부(attached), 고정(pinned), 스케줄링된 작업(scheduled task), 또는 웨이크업(wake-up)이 설정되어 있을 때 재시작되지 않던' 문제가 수정되었습니다.
(Fixed a background session that crashed between turns not being restarted while it was attached, pinned, or had a scheduled task or wake-up set)
스케줄된 웨이크업이나 주기적 작업을 설정한 세션이 턴 간 충돌로 인해 멈춰있었습니다.
v2.1.311부터는 그러한 조건에서도 세션이 재시작되도록 개선되었습니다.
수정 5: auto 모드에서 불필요한 턴 생성
'auto 모드의 백그라운드 에이전트가 자신의 셸(shell)을 기다리는 동안, 웨이크업할 때마다 새로운 메인 대화 턴(main conversation turn)이 시작되던' 문제도 수정되었습니다.
(Fixed background agents in auto mode that wait on their own shells starting a new main conversation turn on every wake)
auto 모드에서 주기적으로 웨이크되는 에이전트가 웨이크업할 때마다 불필요한 대화 턴을 생성하고 있었습니다.
이는 실행 비용과 세션 상태 양쪽에 영향을 미칩니다.
수정 6: SubagentStop 후크의 중복 실행
'종료된 SubagentStop 후크가 완료 시 한 번이 아니라 1분마다 약 두 번 실행되던' 문제가 수정되었습니다.
(Fixed SubagentStop hooks running about twice a minute for each running subagent instead of once when it finishes)
SubagentStop 후크를 사용하는 경우, 이번 수정을 통해 불필요한 중복 실행이 사라집니다.
'수천 줄의 파일을 변경할 때 Write와 Edit가 최대 5초 동안 정지(stalling)하며 0줄 변경을 보고하던' 문제가 수정되었습니다.
(Fixed Write and Edit stalling for up to 5 seconds after they ran, and reporting 0 lines changed, when changing thousands of lines in a file)
대용량 파일에 대한 일괄 변경을 자동화하는 경우, 이 지연 시간은 누적되어 무시할 수 없는 시간이 되곤 했습니다.
또한 "0행 변경"이라는 잘못된 보고가 나오는 바람에, 정상적으로 작성되었는지 확인하기 어려운 상황도 있었다.
"claude -p 및 SDK 세션이 트랜스크립트 메시지를 순서가 뒤섞인 상태로 저장하거나, 취소된 메시지를 유지하는" 문제가 수정되었다.
(Fixed claude -p and SDK sessions saving transcript messages out of order or keeping messages that were taken back)
claude -p를 사용한 파이프라인 처리로 트랜스크립트를 기록 및 분석하는 경우, 이번 수정으로 로그의 신뢰성이 높아진다.
취소된 메시지가 기록에 남아있던 문제는 세션 재구축 및 감사 로그의 정확도에 직접적인 영향을 미치고 있었다.
v2.1.311에서는 신규 기능으로 self-hosted-runner에 --hold-idle-file 및 --max-hold-min 옵션이 추가되었다.
(Added --hold-idle-file and --max-hold-min to self-hosted-runner, to keep an idle session while your host reports processes it left running)
호스트 측에서 "프로세스가 아직 남아있다"고 보고하는 동안, 유휴 세션을 유지할 수 있게 되었다.
self-hosted-runner를 사용하는 팀에게는 실행 완료 후의 세션 관리를 더욱 세밀하게 제어할 수 있게 되었다.
v2.1.311은 수정 건수가 많다. v2.1.309 및 310과 비교했을 때, "기업 환경의 실제 운영에서 막히기 쉬운 지점"에 대응한 수정들이 모여 있는 인상을 준다.
특히, 컨텍스트 상한의 자동 압축(automatic compression), MCP 연결 후 도구 사용(tool usage), 무인 실행 중 세션 재시작은 대규모 자동화를 운영하는 팀에 직접적으로 관련된 변경 사항이다.
UI, 사소한 버그, 클라우드 세션 특유의 수정도 많이 포함되어 있어, 전체 릴리스 크기는 v2.1.309(대규모 버그 수정 릴리스)와 비슷한 규모가 되었다.
컨텍스트 압축이 "어떤 타이밍에", "얼마나 많은 양을" 압축하는지에 대해서는 공식 문서에 자세한 내용이 기재되어 있지 않다.
압축이 들어가면서, 긴 처리 과정의 후반부에서 "이전 결정을 잊은" 것 같은 동작이 증가할 가능성은 있다.
실제 무인 실행 환경에서 200K를 초과하는 사례가 발생했을 때, 압축 후의 처리가 정확하게 계속 진행되고 있는지 확인하기 위한 메커니즘을 별도로 설계해 두는 것이 필요할 수 있다.
self-hosted-runner의 신규 옵션(--hold-idle-file, --max-hold-min)에 대한 구체적인 사용법 역시 현재로서는 공식 샘플을 찾기 어렵다.
본 기사에서 다룬 변경점의 출처는 Claude Code 공식 릴리스 노트 v2.1.311 (https://github.com/anthropics/claude-code/releases/tag/v2.1.311)이다.
기업에서의 AI 추진 및 거버넌스 대응 배경에 대해서는 이 노트도 참고해 주시기 바란다: https://note.com/light_tern636/n/n89f27dc0a4ab
