Claude Code 2.1.278 업데이트: AGENTS.md와 Auto Mode가 바꾸는 팀 운영 방식

Claude Code 2.1.278과 2.1.277 업데이트는 겉으로 보면 작은 개선 목록처럼 보인다. 하지만 팀 단위로 Claude Code를 쓰는 개발 조직에는 꽤 실질적인 변화가 있다. AGENTS.md 지원, 서버 사이드 Auto Mode classifier, 게이트웨이 프록시 옵션, claude -p 오류 처리 개선, 플러그인 설치 안정화가 한꺼번에 들어갔다.

특히 중요한 것은 두 가지다. 첫째, 프로젝트에 CLAUDE.md가 없으면 Claude Code가 AGENTS.md를 프로젝트 지침으로 읽을 수 있게 됐다. 둘째, Claude API, Enterprise, Bedrock, Vertex, Foundry, gateway 환경에서 Auto Mode 분류가 기본적으로 서버 사이드 classifier를 쓰도록 바뀌었다. 둘 다 개인 사용보다 팀 운영에서 영향이 크다.

AGENTS.md 지원이 중요한 이유

그동안 여러 AI 코딩 도구는 프로젝트 지침 파일 이름이 제각각이었다. 어떤 도구는 CLAUDE.md, 어떤 도구는 AGENTS.md, 어떤 도구는 별도 설정 파일을 요구했다. 개발팀 입장에서는 같은 규칙을 여러 파일에 복붙하거나, 도구별로 다른 지침이 섞이는 문제가 생겼다.

Claude Code 2.1.277부터는 프로젝트에 CLAUDE.md가 없을 때 AGENTS.md를 읽는다. 이미 Codex, OpenClaw, 사내 에이전트 워크플로우에서 AGENTS.md를 표준 지침으로 쓰는 팀이라면 중복 관리가 줄어든다. 다만 모든 환경에서 동일하게 적용되는 것은 아니다. 릴리즈 노트 기준으로 Bedrock, Vertex, Foundry 쪽은 아직 제외된다고 되어 있다.

운영 팁은 간단하다. AGENTS.md를 “도구별 프롬프트 모음”으로 만들지 말고, 프로젝트의 실제 작업 규칙으로 만들어야 한다. 예를 들면 다음 항목이다.

빌드와 테스트 명령
금지된 패키지나 아키텍처
브랜치·PR 규칙
코드 스타일과 디렉터리 경계
민감정보 처리 규칙
배포 전 확인해야 할 체크리스트

AI가 읽는 문서라고 해서 장황한 철학을 넣으면 안 된다. 개발자가 PR 전에 보는 운영 문서처럼 짧고 구체적이어야 효과가 있다.

Auto Mode server classifier는 비용과 로그를 확인해야 한다

2.1.278에서는 Auto Mode가 기본적으로 서버 사이드 classifier를 사용하도록 바뀌었다. Auto Mode는 요청 성격에 따라 모델이나 추론 강도를 자동으로 고르는 방식으로 이해하면 된다. 이번 변경의 핵심은 분류 작업이 클라이언트 쪽이 아니라 서버 쪽에서 처리되는 경우가 기본값이 된다는 점이다.

릴리즈 노트는 Bedrock, Vertex, Foundry, gateway 환경에서 CLAUDE_CODE_AUTO_MODE_SERVER=0으로 opt-out할 수 있다고 설명한다. 또 /status에 Auto mode server 행이 추가되어 현재 세션에서 서버 classifier가 쓰이는지 확인할 수 있다.

여기서 팀이 봐야 할 것은 두 가지다. 하나는 비용이다. 서버 classifier 자체가 항상 무료라고 가정하면 안 된다. 릴리즈 노트에도 billed fallback을 경고한다고 되어 있다. 다른 하나는 재현성이다. 자동 분류가 개입하면 같은 프롬프트라도 선택 경로가 바뀔 수 있으므로, 문제 분석 시 /status와 세션 로그를 같이 봐야 한다.

게이트웨이와 프록시 환경 개선

기업 환경에서는 AI 코딩 도구가 인터넷에 직접 나가지 못하는 경우가 많다. 2.1.277에는 CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 옵션과 gateway upstream의 정적 headers 맵이 추가됐다. 프록시가 유일한 egress boundary인 환경에서 호스트명 처리와 헤더 전달을 명확히 하기 위한 기능이다.

이 변화는 보안팀과 플랫폼팀에 의미가 있다. AI 도구가 어디로 나가는지, 어떤 프록시를 통과하는지, 어떤 헤더가 붙는지를 정책으로 관리할 수 있기 때문이다. 개인 개발자는 크게 체감하지 못해도, 대기업이나 금융권처럼 네트워크 경계가 엄격한 조직에서는 도입 난이도를 낮춘다.

다만 프록시 설정은 문서에 남겨야 한다. 로컬 환경변수에만 남아 있으면 새 팀원이 합류했을 때 “왜 Claude Code만 네트워크가 안 되지?”라는 문제가 반복된다.

`claude -p`와 플러그인 오류 개선

이번 업데이트에는 실무자가 바로 체감할 버그 수정도 많다. claude -p와 Agent SDK 세션이 내부 오류 뒤에 결과 없이 멈추는 문제가 수정되어, 이제는 오류를 보고하고 exit code 1로 종료된다. CI나 자동화에서 특히 중요하다. 멈춤은 실패보다 나쁘다. 실패는 재시도와 알림을 걸 수 있지만, 멈춤은 파이프라인을 조용히 막아 버린다.

플러그인 설치도 안정화됐다. 실행 중인 세션이나 다른 프로세스가 쓰는 플러그인 버전을 재설치할 때 설치가 깨지는 문제가 수정되어, 변경이 없으면 기존 복사본을 그대로 둔다. 팀에서 플러그인을 표준화하려면 이런 안정성이 필요하다.

또 Grep과 Glob이 시스템 자원 부족으로 검색을 시작하지 못했을 때 “매치 없음”처럼 보이던 문제도 더 명확한 오류로 바뀌었다. 이건 작지만 중요하다. 검색 실패와 검색 결과 없음은 완전히 다른 상태다.

팀 운영에 적용하는 방법

가장 먼저 할 일은 프로젝트 루트에 있는 AI 지침 파일을 정리하는 것이다. CLAUDE.md와 AGENTS.md가 둘 다 있다면 어떤 파일이 실제 기준인지 결정해야 한다. Claude Code는 CLAUDE.md가 있으면 그것을 우선하고, 없을 때 AGENTS.md를 읽는 구조다. 두 파일의 내용이 다르면 혼란이 생긴다.

업데이트 후 체크리스트

Claude Code 버전을 2.1.278 이상으로 맞춘다.
프로젝트에 CLAUDE.md와 AGENTS.md가 동시에 있는지 확인한다.
팀 표준 지침 파일을 하나로 정하고 중복 내용을 제거한다.
/status에서 Auto Mode server 상태를 확인한다.
Bedrock, Vertex, Foundry, gateway 사용 팀은 CLAUDE_CODE_AUTO_MODE_SERVER=0 opt-out 필요 여부를 검토한다.
CI에서 claude -p를 쓰는 경우 exit code 처리와 timeout을 확인한다.
프록시·게이트웨이 설정은 로컬 메모가 아니라 레포 문서에 남긴다.

이번 업데이트의 방향은 명확하다. Claude Code는 개인용 터미널 도구에서 팀 운영 도구로 이동하고 있다. 그래서 이제 중요한 것은 “답을 잘하나”만이 아니다. 어떤 지침을 읽는지, 어떤 경로로 네트워크를 나가는지, 자동 분류가 비용과 결과에 어떤 영향을 주는지까지 관리해야 한다.