Claude Code, CLAUDE.md 없으면 AGENTS.md를 프로젝트 지침으로 읽는다

Claude Code가 프로젝트 지침 파일을 찾는 순서가 바뀌었다. 프로젝트에 CLAUDE.md가 없으면 이제 AGENTS.md를 대신 읽는다. Claude Code 전용 파일을 따로 두지 않은 저장소라도, 다른 코딩 에이전트와 공유하던 규약 파일을 그대로 활용할 수 있게 된 것이다.

동작은 /config의 'Project instructions' 항목에서 조정한다. 다만 이 지원은 아직 Amazon Bedrock, Google Vertex AI, Foundry를 경유하는 환경에서는 빠져 있다. 같은 릴리스에서 SDK와 헤드리스(-p) 실행의 세션 시작 방식도 손봤는데, 첫 턴이 디렉터리별 CLAUDE.md 조회를 기다리지 않게 되어 초기 응답이 가벼워졌다.

게이트웨이를 운영하는 팀을 위한 옵션도 늘었다. CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1을 켜면 외부로 나가는 모든 요청이 호스트명을 로컬에서 해석하지 않고 포워드 프록시에 그대로 전달된다. 게이트웨이 업스트림에는 선택적으로 headers 맵을 붙일 수 있어, 공급자 앞단에 두는 프록시로 정적 헤더를 보낼 수 있다.

배경에는 코딩 에이전트마다 제각각인 지침 파일 문제가 있다. CLAUDE.md는 Claude Code 전용 규약이었고, 다른 도구는 저마다 다른 이름의 파일을 요구해 왔다. 여러 에이전트를 함께 쓰는 팀은 같은 내용을 여러 파일에 중복 관리해야 했다. AGENTS.md를 공통 진입점으로 삼으려는 움직임은 이런 중복을 줄이려는 시도로 읽힌다.

이번 변경에는 안정성 수정도 대거 묶여 있다. 내부 오류 뒤 결과 없이 멈추던 claude -p와 Agent SDK 세션이 이제 오류를 알리고 종료 코드 1로 끝난다. 이전 어시스턴트 턴에 빈 텍스트 블록이 섞여 있으면 매 요청이 'text content blocks must be non-empty'로 실패하던 문제, 구버전 빌드와 최신 빌드가 한 기기에 공존할 때 예기치 않게 로그아웃되던 문제도 정리됐다.

도구 동작에서도 손볼 곳이 많았다. 시스템 자원이 고갈돼 검색을 시작하지 못했을 때 Grep과 Glob이 '일치 없음'으로 조용히 넘어가던 동작이 명시적 오류로 바뀌었고, Write 도구는 대상 경로가 이미 디렉터리일 때 권한 거부로 턴을 끝내는 대신 원인을 분명히 알려준다. Edit 도구가 이스케이프된 역슬래시 뒤의 uXXXX 텍스트를 유니코드 이스케이프로 오인하던 문제, 비ASCII 문자가 섞인 큰 편집이 파일과 맞지 않을 때 엉뚱한 정규식 오류를 내던 문제도 수정됐다.

플러그인과 세션 관리 쪽 수정도 눈에 띈다. 사용 중인 플러그인 버전을 재설치할 때 설치본이 깨지던 문제, 제거한 플러그인이 'failed to load' 행으로 되살아나던 문제, 공식 마켓플레이스 플러그인이 커밋 정보 없이 기록되던 문제 등이 포함됐다. 업데이트 확인이 30분마다 오류를 내거나 프록시가 잘못된 버전을 돌려줄 때 claude update가 멈추던 상황, winget이나 apk로 관리되는 설치에서 버전 조회 실패를 '최신 버전'으로 잘못 보고하던 문제도 고쳐졌다.

실무에서는 팀 저장소에 AGENTS.md 하나만 두고 여러 에이전트를 함께 굴릴 수 있는지부터 점검해볼 만하다. 이미 CLAUDE.md를 쓰고 있다면 동작이 그대로 유지되므로 급하게 바꿀 이유는 없다. 설치 버전은 claude --version으로 확인하고, 최신 릴리스로 올린 뒤 /config에서 지침 파일 설정을 확인하는 편이 안전하다.

주의할 점은 적용 범위다. AGENTS.md 지원은 Bedrock, Vertex, Foundry 경유 환경에서 아직 동작하지 않으므로, 해당 인프라를 쓰는 조직은 별도 지침 파일을 유지해야 한다.