claudekit / updates / claude-code-2-1-277
[ PATCH · ]

Claude Code 2.1.277

CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 대신 읽는 기능이 추가됐고, Claude apps gateway에 포워드 프록시 전용 환경 변수와 업스트림 `headers:` 설정이 생겼습니다. 사용 중단된 TaskOutput 도구가 제거됐고, 서브 에이전트 결과는 별도 머리글 아래 들여쓰기로 전달돼 세션 지시로 오인되지 않습니다. 버그 수정에는 내부 오류 뒤 `claude -p`와 Agent SDK 세션이 결과 없이 멈추던 문제, 빈 텍스트 블록 때문에 모든 요청이 실패하던 문제, 오래된 Claude Code 빌드가 같은 컴퓨터에서 실행되면 로그아웃되던 문제가 포함됩니다.

Claude Code
공식 발표 →

이 글은 공식 문서를 바탕으로 요약·정리한 내용입니다.

무엇이 바뀌었나?

Claude Code 2.1.277이 2026년 9월 18일 출시됐습니다. 가장 큰 변화는 AGENTS.md 지원입니다. AGENTS.md만 둔 프로젝트에서도 따로 CLAUDE.md를 만들지 않고 프로젝트 지침을 불러올 수 있습니다. 보안 측면에서는 서브 에이전트 결과와 워크플로 스크립트 프롬프트가 세션의 지시나 사용자 입력으로 읽히지 않도록 전달 형식이 바뀌었고, 프롬프트에 숨은 보이지 않는 유니코드 문자를 제거합니다. 버그 수정은 헤드리스 실행과 세션 재개, ~/.claude.json의 잘못된 값으로 인한 충돌, 플러그인 설치와 관리 화면에 넓게 걸쳐 있습니다.

새 기능

  • AGENTS.md 지원

    프로젝트 지침을 AGENTS.md에만 적어 둔 프로젝트에서는 Claude Code가 이를 읽지 않아, 같은 내용을 CLAUDE.md에 따로 옮겨 관리해야 했습니다. 이제 CLAUDE.md가 없는 프로젝트에서는 AGENTS.md를 대신 읽습니다. 이 동작은 /config의 “Project instructions”에서 바꿀 수 있습니다. Bedrock, Vertex, Foundry에서는 아직 지원하지 않습니다.

  • CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

    Claude apps gateway(조직이 직접 운영하는 Claude 앱용 게이트웨이)가 외부로 나가는 통로가 포워드 프록시 하나뿐인 환경에서는, 게이트웨이가 호스트 이름을 직접 조회하려다 실패할 수 있었습니다. 이 환경 변수를 켜면 모든 외부 요청에서 호스트 이름을 로컬에서 조회하지 않고 프록시에 그대로 넘깁니다.

  • 게이트웨이 업스트림의 headers: 설정

    모델 제공자 앞에 자체 프록시를 두면 인증용 헤더 등을 따로 붙일 방법이 없었습니다. 이제 Claude apps gateway 업스트림에 선택 항목인 headers: 맵을 지정해 프록시로 고정 헤더를 보낼 수 있습니다.

  • 백그라운드 작업 업데이트 대기 표시

    /tasks 같은 패널을 열어 둔 사이에 백그라운드 작업이 끝나면 결과가 도착했는지 알기 어려웠습니다. 이제 작업 업데이트가 대기 중이라는 줄이 표시됩니다.

  • [VSCode] 새로 추가된 기능

    패널 메뉴에 Sign out 항목(입력 명령은 /logout)이 생겼습니다. 에이전트 맵에 백그라운드 셸과 실행 중인 작업이 Stop 버튼과 함께 표시되고, /tasks로 열 수 있습니다. 응답마다 Copy response 버튼(입력 명령은 /copy)이 생겼고, 비활성 세션이 자동 보관될 때 한 번 안내가 뜨며 Archived 그룹에 “Unarchive all”이 추가됐습니다. 플랜 사용량 한도가 적용되지 않는 환경(Vertex, Bedrock, Foundry, API 키)에서는 Account & usage 대화상자와 세션 관리자에 세션 비용과 토큰 사용량이 표시됩니다.

  • [Claude Code on the web] 환경 선택기의 개인, 조직 구분

    Team, Enterprise 플랜의 환경 선택기에 Personal, Organization 섹션이 생겼고, 관리자는 개인 환경을 조직과 공유할 수 있습니다.

주요 개선

시작 속도와 안내 메시지

  • SDK, 헤드리스 실행의 시작 속도

    SDK나 -p로 실행하면 첫 턴이 디렉터리별 CLAUDE.md 조회를 기다린 뒤에 시작됐습니다. 이제 이 조회를 기다리지 않습니다.

  • claude plugin install로 이미 설치된 플러그인을 다시 설치할 때

    이미 설치돼 있다는 사실만 알 수 있었습니다. 이제 마켓플레이스에 더 새로운 버전이 있으면 알려 주고 claude plugin update 명령을 안내합니다.

  • 위험한 rm 명령의 권한 확인

    어떤 rm 명령이 문제인지 드러나지 않아 헤드리스 실행에서 대응하기 어려웠습니다. 이제 문제가 된 rm 명령을 보여 주고, 변수가 비어 있을 때 멈추도록 하는 ${VAR:?} 가드를 제안합니다.

  • /ultrareview에서 검토할 내용이 없을 때

    이유를 구분하지 않고 같은 안내만 나왔습니다. 이제 어떤 경우인지 알려 주고 최근 커밋을 검토하는 명령을 제안하며, 새 저장소의 첫 커밋은 전체를 검토합니다.

  • 기타 안내 개선

    Claude apps gateway의 루프백 오류 메시지가 CLAUDE_GATEWAY_ALLOW_LOOPBACK을 알려 주고, /plugin Installed 탭에서 플러그인과 따로 표시되는 MCP 서버가 어느 플러그인 소속인지 보여 줍니다. 로고 아래의 넘친 시작 안내 줄은 “+N more · /status” 대신 “N more notices hidden”으로 표시됩니다.

프롬프트와 아티팩트

  • 프롬프트의 보이지 않는 문자 제거

    눈에 보이지 않는 유니코드 서식 문자나 태그 문자가 프롬프트에 섞여 들어가도 알 수 없었습니다. 이제 이런 문자를 제거하고, 정리된 프롬프트를 보내기 전에 확인할 수 있도록 보여 줍니다.

  • claude.ai 아티팩트 링크 읽기

    Artifact 도구를 쓸 수 있는 환경에서는 claude.ai 아티팩트 링크를 WebFetch 대신 Artifact 도구로 읽습니다. Artifact 도구의 권한 확인 문구도 짧아졌고, 페이지와 아티팩트를 제목이나 파일 이름으로 표시하며 링크는 본문 뒤에 나열합니다.

동작이 바뀐 항목

  • TaskOutput 도구 제거 (변경)

    사용 중단(deprecated) 상태였던 TaskOutput 도구가 제거됐습니다. Claude는 백그라운드 작업의 출력 파일을 Read 도구로 읽으며, taskOutputMaxChars 설정과 TASK_MAX_OUTPUT_LENGTH는 더 이상 효과가 없습니다.

  • 서브 에이전트 결과 전달 형식 (변경)

    서브 에이전트가 돌려준 텍스트가 세션 자체의 지시처럼 읽힐 여지가 있었습니다. 이제 결과가 서브 에이전트 출력임을 표시하는 머리글 아래 들여쓰기로 전달됩니다. Bedrock, Vertex, Foundry에서는 워크플로 스크립트가 agent()로 계산해 넘긴 프롬프트도 스크립트가 작성한 텍스트로 표시돼, 안전 분류기가 이를 사용자 입력으로 읽지 않습니다.

  • Bedrock, Vertex, Foundry의 Bash 샌드박스 안내 (변경)

    Anthropic API와 같은 문구로 바뀌어, 샌드박스를 작업에 주어진 범위의 경계로 설명합니다.

  • /model의 Fable 표시 (변경)

    Anthropic API에서는 Fable이 항상 /model에 표시되며, 조직 설정으로 꺼져 있을 때만 회색으로 비활성화됩니다.

  • 비대화형 /ultrareview (변경)

    저장소에 기준 브랜치나 공유 이력이 없으면 실행을 거부합니다.

  • claude -p의 자동 제목 요청 제거 (변경)

    SDK나 IDE 밖에서 실행한 claude -p에서는 백그라운드로 Haiku에 보내던 자동 제목 요청을 하지 않습니다.

  • [Claude Code on the web] 조직 환경과 관리자 설정 (변경)

    Team, Enterprise 플랜에서 조직 환경은 Code 탭에서 읽기 전용 요약으로 열리고, 편집은 Admin settings → Cloud environments에서 합니다. 관리자 설정의 “Web” 항목은 “Cloud sessions”로 이름이 바뀌었고, 그 아래의 중복된 읽기 전용 Mobile 행은 제거됐습니다.

  • [Claude Tag] Pylon 자격 증명 프리셋 (변경)

    관리자가 Pylon의 EU 호스트를 지정할 수 있습니다.

주요 버그 수정

헤드리스와 세션 재개

  • 내부 오류 뒤 claude -p와 Agent SDK 세션이 결과 없이 멈추던 문제 수정. 이제 오류를 보고하고 종료 코드 1로 끝납니다.
  • 이전 assistant 턴에 다른 콘텐츠와 함께 빈 텍스트 블록이 있으면 --resume 이후를 포함해 모든 요청이 “text content blocks must be non-empty”로 실패하던 문제 수정.
  • 헤드리스 재개(claude -p --resume, SDK, VS Code 확장 창 다시 불러오기)에서 세션 비용과 사용량 합계가 0부터 다시 시작하던 문제 수정. 헤드리스 세션은 종료할 때 합계를 저장합니다.
  • 저장된 기록에 문자열 형태의 assistant 메시지나 형식이 잘못된 stop hook 요약이 있으면 세션 재개 시 충돌하던 문제 수정.
  • /clear 뒤 이어서 시작한 세션(재시작, --continue, --resume)에서 SessionStart 훅이 출력을 내면 첫 메시지 일부가 빠져 프롬프트 캐시가 전혀 적중하지 않던 문제 수정.
  • 재개한 서브 에이전트와 팀원 에이전트가 불러온 MCP 도구 정의를 다시 렌더링해 프롬프트 캐시가 깨지던 문제, 재개나 재실행 후 이전 첨부가 다시 렌더링돼 extended thinking이 빠지고 캐시가 적중하지 않던 문제 수정.
  • Claude가 작업하는 중에 입력한 메시지를 모델이 가끔 무시하던 문제 수정.

로그인과 설정 파일

  • IDE 확장에 번들된 CLI처럼 오래된 Claude Code 빌드가 같은 컴퓨터에서 실행되면 예기치 않게 로그아웃되던 문제 수정.
  • ~/.claude.json의 customApiKeyResponses, theme, claudeAiMcpEverConnected 값이나 placeholder 기록의 형식이 잘못되면 시작이 멈추거나, 실행 시 또는 /mcp, /plugin manage를 열 때 충돌하거나, Remote Control 세션 관리가 실패하던 문제 수정.
  • claude.ai 로그인이 취소된 뒤 오류가 만료된 Anthropic 프로필을 원인으로 지목하던 문제 수정. 이제 /login을 먼저 안내합니다.
  • 서버가 API 키 생성을 거부하면 Console 로그인에 “Request failed with status code 400”만 표시되던 문제 수정. 이제 서버 메시지를 보여 줍니다.

업데이트

  • 프록시가 잘못된 버전을 돌려주면 30분마다 업데이트 확인이 오류를 내고, 최소, 최대 버전을 지정한 경우 claude update가 멈추던 문제 수정. 형식이 잘못된 minimumVersion은 무시합니다.
  • winget이나 apk로 설치한 경우 버전 조회가 실패해도 claude update가 “up to date”로 보고하던 문제 수정.
  • 자동 업데이트가 실패하면 ~/.cache/claude/staging에 큰 다운로드 파일이 남던 문제 수정.

도구와 샌드박스

  • 프로세스, 메모리, 파일 핸들이 바닥나 검색을 시작하지 못해도 Grep과 Glob이 “일치 없음”으로 보고하던 문제 수정. 이제 그 이유를 오류로 알립니다.
  • 대상 경로가 기존 디렉터리이면 Write 도구가 권한 거부처럼 조용히 턴을 끝내던 문제 수정. 이제 명확한 오류를 보고합니다.
  • Edit 도구가 이스케이프된 백슬래시 뒤의 uXXXX 텍스트를 \uXXXX 이스케이프로 해석해, 비 ASCII 문자 편집이 엉뚱한 부분을 바꿀 수 있던 문제 수정.
  • 비 ASCII 텍스트가 든 아주 큰 편집이 파일과 맞지 않으면 Edit 도구가 “String not found in file” 대신 “Invalid regular expression: regular expression too large”를 보고하던 문제 수정.
  • 도구 호출의 파일 경로에 �이 이스케이프 형태로 들어 있으면 “Path contains null bytes”로 턴이 일찍 끝나던 문제 수정. 이스케이프된 제어 문자는 문자 그대로 유지됩니다.
  • 샌드박스가 켜진 상태에서 샌드박스 밖에서 실행되는 Bash 명령의 $TMPDIR이 빈 값으로 확장되던 문제 수정.
  • sandbox.excludedCommands glob이 복합 Bash 명령의 일부에만 맞아도 명령 전체를 샌드박스에서 제외하던 문제 수정. 이제 모든 부분이 맞아야 합니다.
  • Windows에서 작업 폴더 경로가 길면(약 120자 이상) PDF 페이지 읽기가 실패하던 문제 수정.
  • Cowork 클라우드 세션의 WebFetch, WebSearch가 요청이 거부된 이유(가져오기 한도 소진, 관리자 정책 등)를 Claude에 알리지 않던 문제 수정.
  • 아티팩트 게시가 속도 제한에 걸리면 Claude에 재시도를 멈추라고 알리던 문제 수정. 이제 게시되지 않았다는 사실과 언제 같은 게시를 다시 보내면 되는지 알려 줍니다.

화면과 입력

  • 기록에서 불러온 프롬프트나 외부 편집기에서 가져온 텍스트에 터미널 색상 코드가 섞여 있으면 “unrecoverable interface error”로 충돌하던 문제 수정.
  • 느리거나 부하가 큰 컴퓨터에서 첫 스피너가 나타날 때 “Claude Code exited after an unrecoverable interface error”로 종료되던 문제, 내부 렌더링 오류 뒤 세션이 끝날 때까지 화면이 갱신되지 않던 드문 문제 수정.
  • Windows에서 Claude가 답한 직후 “Out of memory” 같은 오류로 턴이 멈춰 응답의 도구 호출이 실행되지 않던 드문 문제 수정.
  • 턴 도중 도착한 다른 에이전트의 메시지(서브 에이전트의 SendMessage 등)가 도착한 위치가 아니라 “Ran N shell commands” 줄 아래에 표시되던 문제 수정.
  • 전체 화면 /resume 선택기처럼 프롬프트 영역을 덮는 패널에서 드래그로 텍스트를 선택해도 “copied” 알림이 나오지 않던 문제 수정.
  • claude agents 입력창에서 키를 누르고 있거나 아주 빠르게 입력하면 입력하거나 붙여 넣은 텍스트가 뒤섞이던 문제 수정.
  • keybindings.json에서 Chat 컨텍스트의 Enter를 chat:queueSubmit 등으로 바꾸면 에이전트 패널 행에서 Enter가 동작하지 않던 문제 수정.

플러그인과 스킬

  • 세션이나 다른 프로그램이 쓰고 있는 플러그인 버전을 다시 설치하면 claude plugin install이 실패하고 설치된 사본이 망가지던 문제 수정. 바뀌지 않은 사본은 그대로 둡니다.
  • strictKnownMarketplaces나 blockedMarketplaces 항목 하나의 형식이 잘못되면 엔터프라이즈 마켓플레이스 정책 전체가 조용히 꺼지던 문제 수정.
  • 공식 마켓플레이스 플러그인이 installed_plugins.json에 커밋 정보 없이 기록되고, 특정 커밋에 고정한 플러그인을 업데이트해도 이전 커밋이 남던 문제 수정.
  • /plugin Installed 탭과 /skills가 constructor나 toString처럼 내장 Object 속성과 같은 이름의 스킬, 명령에서 충돌하던 문제 수정.
  • /plugin에서 제거한 플러그인이 “failed to load” 행으로 다시 나타나고 Remove로 지워지지 않던 문제, 다중 선택 설치가 모두 실패하면 아무 메시지 없이 닫히던 문제, Installed 탭 메시지에서 터미널 제어 문자를 제거하지 않던 문제 수정.
  • 플러그인 다시 불러오기 미리보기가 압축 해제한 사본을 종료할 때까지 남기고, 다운로드 실패 시 되돌아갈 캐시된 --plugin-url 압축 파일을 덮어쓰던 문제 수정.
  • .claude/skills가 git에 추적되지 않으면 --worktree 세션에서 메인 저장소의 프로젝트 스킬을 불러오지 않던 문제 수정.
  • 플러그인의 LSP 서버가 종료되거나 stdin을 닫으면 백그라운드 세션(claude --bg)이 종료되던 문제 수정.

Claude apps gateway

  • 프록시를 설정한 경우 게이트웨이의 텔레메트리 중계가 NO_PROXY에 적은 수집기 호스트 이름이나 도메인을 무시하던 문제 수정.

[VSCode]

  • “General config” 메뉴가 설정을 여는 대신 /config 사용법을 표시하던 문제 수정. 입력한 /mcp, /hooks, /memory, /rewind 등도 해당 대화상자를 엽니다.
  • /effort로 수준을 저장한 모델에서 effort 슬라이더 값이 다음 세션에 유지되지 않던 문제 수정.
  • 저장된 모델 설정이 “Sonnet”처럼 대소문자가 다른 별칭이면 이미 쓰던 패널에서 연 대화의 모드 선택기에 Auto가 빠지던 문제 수정.
  • /fast가 fast mode를 기본값으로 저장하지 않아 확장이 Claude Code를 다시 실행하면 풀리던 문제 수정.

[Claude Code on the web]

  • Custom 네트워크 접근으로 저장한 클라우드 환경에 도메인이 없으면 조용히 Trusted로 되돌아가던 문제 수정. 이제 대화상자에서 도메인을 하나 이상 입력하도록 요구합니다.

[Claude Tag]

  • Enterprise Grid 조직 전체 설치에서 Slack 채널에 만든 루틴이 실행될 때 워크스페이스의 다른 공개 채널을 읽지 못하던 문제 수정.
  • 액세스 번들의 자격 증명 프리셋에 있는 “Learn more” 링크가 일반 API 참조 대신 각 업체의 자격 증명 설정 페이지를 열도록 수정.
  • Google Cloud 자격 증명 양식에서 거부된 키 파일의 이유를 알리지 않던 문제 수정. 웹사이트와 scope 값은 잠긴 상태로 유지되고, 교체가 거부돼도 붙여 넣은 키가 남습니다.
  • AWS 서명, 클라이언트 인증서, 사용자 지정 CA를 쓰는 연결을 거친 요청에서 관리자 설정의 네트워크 이벤트 로그에 응답 상태가 표시되지 않던 문제 수정.

알아두면 좋은 점

  • AGENTS.md는 CLAUDE.md가 없을 때만 읽습니다 — 두 파일이 모두 있으면 기존처럼 CLAUDE.md를 사용합니다. 동작은 /config의 “Project instructions”에서 바꿀 수 있고, Bedrock, Vertex, Foundry에서는 아직 지원하지 않습니다.
  • TaskOutput 도구에 의존하던 설정은 정리가 필요합니다 — taskOutputMaxChars 설정과 TASK_MAX_OUTPUT_LENGTH 환경 변수는 더 이상 효과가 없습니다.
  • sandbox.excludedCommands가 더 엄격해졌습니다 — 복합 명령(&&, | 등으로 이어진 명령)은 모든 부분이 glob에 맞아야 샌드박스에서 제외됩니다. 일부만 맞도록 작성한 규칙은 이제 명령 전체를 제외하지 않습니다.
  • 헤드리스 실행은 오류 시 종료 코드 1로 끝납니다 — claude -p나 Agent SDK를 스크립트에서 쓴다면 멈춤 대신 종료 코드로 실패를 감지할 수 있습니다.
  • 보내기 전에 프롬프트가 바뀔 수 있습니다 — 보이지 않는 유니코드 서식 문자나 태그 문자가 있으면 제거된 프롬프트가 확인용으로 표시됩니다.