이 글의 결론은 다음과 같습니다: v2.1.312 버전에는 Entra ID의 OIDC 클레임 대응, managed settings 가져오기 오류 수정, 대규모 CLAUDE.md 덮어쓰기 문제 수정 등 기업 환경에서의 안정적인 운영과 관련된 여러 변경 사항이 포함되어 있습니다. Bedrock, Vertex, Foundry, Mantle 시스템 프롬프트 동작 방식도 변경되었습니다.
- Claude Code를 기업 환경(Bedrock, Vertex, Foundry, Mantle, VS Code 확장)에서 사용하고 있는 사용자
- Claude Tag로 Slack 연동을 사용하는 팀
- 대규모 CLAUDE.md나 긴 규칙 파일을 사용하는 프로젝트
출처: Claude Code v2.1.312 Release Notes (2026-10-27T20:24:20 UTC)
v2.1.311 다음 날에 v2.1.312가 출시되었습니다. v2.1.311이 기업 운영 환경의 버그 수정에 중점을 두었던 것과 마찬가지로, v2.1.312 역시 사소하지만 영향력이 큰 변경 사항들이 나열되어 있습니다. 특히 CLAUDE.md 덮어쓰기 문제와 managed settings 가져오기 오류는 무인 실행 환경에서 운영하는 경우 반드시 확인해야 합니다.
Claude apps 게이트웨이에 oidc.user_id_claim이 추가되었습니다. 이를 통해 sub 외의 ID 토큰 클레임(Microsoft Entra ID의 oid 등)으로 사용자를 식별할 수 있게 되었습니다.
Entra ID를 이용한 싱글 사인온(Single Sign-On) 통합을 진행하는 기업에서는 oid 클레임을 사용하는 경우가 많습니다. 이전에는 sub로만 사용자를 식별할 수 있다는 제약이 해소되었습니다. Entra ID 통합을 검토 중이라면 이 변경 사항을 확인해 볼 가치가 있습니다.
VS Code 확장 프로그램에서 로그인한 후, 세션 잔여 시간 동안 managed settings와 organization policy가 가져와지지 않던 오류가 수정되었습니다.
이 오류는 VS Code 확장 프로그램을 통해 Claude Code에 로그인하면 이후 전체 세션 동안 조직의 정책(organization policy)이 적용되지 않을 가능성이 있었습니다. 무인 실행이나 팀 멤버가 VS Code를 통해 사용하는 환경에서는 영향을 줄 수 있습니다. 이 문제는 수정되었지만, 과거에 정책 위반으로 의심되는 동작이 있었다면 v2.1.312로 업데이트하면서 해결될 것입니다.
Bedrock, Vertex, Foundry, Mantle에서 Claude Code가 인식하지 못하는 모델 이름(커스텀 배포명, inference profile ARN 등)에 대해 짧은 시스템 프롬프트(system prompt)를 사용하도록 변경되었습니다. 이전에는 긴 시스템 프롬프트가 사용되곤 했습니다.
이전 동작으로 되돌리고 싶다면 환경 변수 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0로 설정할 수 있습니다. 커스텀 배포명을 사용하는 기업이라면 이 변경된 이후의 동작을 확인해 두는 것이 좋습니다.
마찬가지로, 플래그가 붙은 메시지(flagged message) 이후 자동 모델 전환 역시 Claude Code가 인식하지 못하는 모델 이름에 적용되도록 변경되었습니다. 이 기능도 비활성화하려면 CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=1로 설정할 수 있습니다.
prompt 훅과 agent 훅은 세션당 최대 24개(서브 에이전트 포함)가 동시에 실행될 수 있게 되었습니다. 또한, 타임아웃을 초과하여 대기 중인 훅은 최대 12개까지 가능합니다. 타임아웃 시간이 1초 미만일 경우에는 1초로 간주됩니다.
자동화 파이프라인에서 다수의 훅을 사용하는 경우, 이 상한선이 영향을 주는지 확인해 두는 것이 좋습니다. 특히 서브 에이전트를 여러 개 병렬로 구동하는 구성에서는 주의가 필요합니다.
서브 에이전트의 autoCompactWindow 기능은 CLAUDE_CODE_AUTO_COMPACT_WINDOW로 설정한 값을 낮추는 방향으로만 적용되도록 변경되었습니다. 이전에는 효과가 없었던 부분이었습니다. '높이는' 방향으로는 여전히 변함이 없다는 점에 주의해야 합니다.
Claude Code가 매우 큰 CLAUDE.md, 규칙 파일, 또는 @include된 파일을 맨 앞 부분만 읽은 상태에서 Write 도구로 덮어쓰기 하던 오류가 수정되었습니다. 이제는 Write 기능이 파일 전체를 읽거나 in-place 편집을 요구하게 되었습니다.
이는 실제 사용 환경에서는 심각해질 수 있는 문제입니다. 대규모 CLAUDE.md를 사용하는 경우, Claude가 '처음 몇천 토큰'만 읽은 채 덮어쓰기를 하면 뒷부분에 작성된 규칙이 전부 사라질 가능성이 있었습니다. v2.1.312에서 수정되었습니다.
Bash에서 cd
명령어로 git 리포지토리의 깊은 위치로 이동한 후, paths: 스킬을 찾을 수 없던 문제가 수정되었습니다. cd를 사용한 스크립트 내에서 스킬을 호출할 경우, 제대로 작동하는지 다시 확인할 수 있습니다.
유효하지 않은 이름의 커맨드 때문에 모든 커맨드가 로드되지 않아, claude -p가 아무것도 출력하지 않던 문제가 수정되었습니다. 사용자 정의 커맨드를 사용하는 환경에서는 설정을 확인할 계기가 될 것입니다.
Read 도구가 오래된 세션 파일 삭제와 같은 시점에 실행될 때, "pdftoppm failed: Could not write image" 오류로 PDF 페이지 로드에 실패하던 문제가 수정되었습니다. PDF 처리를 파이프라인(pipeline)에 통합한 경우 확인해 주십시오.
터미널에서 세션을 재개한 후, 첫 번째 응답이 다음에 세션을 재개할 때 누락되던 희귀한 사례가 수정되었습니다.
-
조직 설정이 로드되지 않거나 시작 시 거부된 경우,
종료 코드(exit code)만으로 종료하던 세션이, 탭에 이유를 표시하고 "Retry", "Sign in again"을 제시하도록 변경됨 - 이용 제한 리셋 표시가 시간("3:10 PM에 리셋") 형식으로 통일되었고, "5시간 제한" 표기로 통합됨
-
Anthropic 공식 마켓플레이스 플러그인에서 선언된 고정 URL 타입 원격 MCP 서버 이름이 사용자 정의 이름이 아닌 실제 이름으로 보고되도록 변경됨
-
Slack에서의 Claude Tag 재시도 알림이 일반적인 API 오류 메시지가 아니라 모델명 또는 속도 제한(rate limit) 관련 내용을 표시하도록 변경됨
-
공개된 오래된 비공개 Slack 채널이 새로운 ID를 가질 경우, Claude Tag 채널의 on/off 스위치와 에이전트 설정이 워크스페이스 기본값으로 폴백되던 문제가 수정됨
-
네트워크 접근이 "None"으로 설정된 환경의 채널에서 Claude in Slack이 응답하지 않던 문제가 수정됨
-
CLAUDE.md가 클 경우(수천 줄 이상): v2.1.312로 업데이트하면 덮어쓰기(overwrite) 문제가 해소됩니다.
-
VS Code를 통해 로그인한 사용자가 있을 경우: 관리 설정(managed settings)이 올바르게 적용되도록 변경되었습니다.
-
Bedrock, Vertex, Foundry, Mantle을 사용하는 경우: 사용자 정의 배포명/ARN의 시스템 프롬프트 동작이 변경되었습니다 (원상 복구하려면 환경 변수로 설정 필요).
-
Claude Tag로 Slack 연동 시: 재시도 알림 메시지와 채널 ID 문제가 수정되었습니다.
-
많은 훅(hook)을 사용하는 경우: 동시 실행 제한(24/12)을 확인해야 합니다.
v2.1.311과 312가 연속해서 출시되었으며, 특히 CLAUDE.md의 덮어쓰기 문제는 서둘러 대응하고 싶은 수정입니다.
Claude의 자동화 실행 환경에 대해서는 별도로 정리하였습니다.
