Claude Code, AGENTS.md 지원 시작: CLAUDE.md가 없을 때 읽습니다

AGENTS.md 지원, 핵심은 ‘없을 때 대신 읽기’입니다

AI 코딩 도구를 함께 쓰면 같은 프로젝트 지침을 여러 파일에서 관리하기도 합니다. 테스트 방법이나 코딩 규칙을 바꿀 때 문서마다 수정해야 한다면 내용이 서로 달라질 수 있습니다.

앤트로픽은 공식 변경 기록 기준 2026년 9월 18일 업데이트에서 Claude Code의 AGENTS.md 지원을 발표했습니다. 기능이 추가된 버전은 2.1.277입니다. 이 글은 직접 실행한 리뷰가 아니라 공식 변경 기록을 정리한 뉴스입니다.

적용 조건은 프로젝트에 CLAUDE.md 가 없을 때 AGENTS.md 를 대신 읽는 fallback입니다. 원래 사용할 파일이 없으면 다른 파일을 읽는 방식입니다.

CLAUDE.md 가 폐지되거나 AGENTS.md 가 항상 우선하는 것은 아닙니다. 두 파일의 내용을 자동으로 병합한다는 뜻도 아닙니다. 이미 AGENTS.md 를 유지하던 팀에는 지침 중복 관리 부담을 줄일 선택지가 늘었습니다.

/config 설정과 플랫폼 예외를 확인합니다

관련 설정은 /config 의 Project instructions에서 변경할 수 있습니다. 다만 이번 변경 기록에는 내부 JSON 키, 기본값, 구체적인 선택지 이름이 안내돼 있지 않습니다. 하위 폴더 탐색 우선순위나 전역 경로 규칙도 추정하지 않아야 합니다.

플랫폼 예외도 있습니다. 출시 당시 Bedrock·Vertex·Foundry에서는 이번 AGENTS.md fallback 지원이 아직 제공되지 않습니다.

이는 Claude Code 전체가 해당 플랫폼에서 작동하지 않는다는 뜻이 아닙니다. 이번에 추가된 지침 파일 지원에 한정된 예외입니다. 요금제나 API 키 계정 제한, 한국 지원 여부, 특정 운영체제 범위는 이 변경 기록만으로 단정할 수 없습니다.

적용 전에는 기존 파일부터 살펴봅니다

실무에서는 먼저 claude --version 으로 설치 버전을 확인하는 것을 권합니다. 이어서 프로젝트에 CLAUDE.md 가 있는지 살펴보고, /config 의 Project instructions를 확인합니다.

기존 CLAUDE.md 가 잘 작동한다면 이번 소식만 보고 삭제하거나 이름을 바꿀 필요는 없습니다. 두 파일이 모두 있다면 내용을 합치기 전에 팀 운영 기준부터 정하는 편이 안전합니다. 공통 지침을 어디에서 관리하고 누가 변경을 검토할지 합의하는 방식입니다.

AGENTS.md 를 활용할 때는 기존 테스트 명령, 코딩 규칙, 수정 제외 범위가 현재 저장소와 맞는지도 점검합니다. 오래된 명령이나 실제 작업과 다른 규칙은 파일을 읽게 하는 것만으로 해결되지 않습니다. 이 목록은 권장 문서 내용이지 강제 스키마나 필수 필드가 아닙니다.

보안은 별도 문제입니다. 파일에 비밀키를 넣지 않고 외부 기여자가 바꾼 지침은 코드처럼 검토하는 것을 권합니다. ‘수정 금지’라는 문구만으로 실제 파일 접근 권한이 차단되지는 않으므로 필요한 제한은 별도 권한·승인 체계로 관리해야 합니다.

개발 자동화의 실패를 더 명확히 알립니다

같은 버전에는 개발 자동화에서 눈여겨볼 운영 수정도 포함됐습니다. 공통점은 정상 결과와 실행 실패를 더 분명하게 구분하도록 했다는 점입니다.

먼저 claude -p 와 Agent SDK 세션이 내부 오류 뒤 결과 없이 멈출 수 있었던 문제를 수정했습니다. 해당 상황에서는 이제 오류를 알리고 종료 코드 1을 반환합니다. 모든 종류의 오류나 정지 상황이 해결됐다는 보장은 아닙니다.

Grep·Glob은 프로세스·메모리·파일 핸들 부족으로 검색을 시작하지 못했는데도 이전에는 일치하는 결과가 없는 것으로 보고하던 문제를 수정했습니다. 이제는 검색을 시작할 수 없었다는 오류를 명시합니다.

운영상 중요한 차이는 ‘검색 결과가 정말 없음’과 ‘검색 자체를 실행하지 못함’을 구분한다는 것입니다. 기존의 모든 검색 결과 0건이 오류였다는 뜻은 아닙니다. 자원 부족으로 검색을 시작하지 못한 상황의 보고 방식이 바로잡힌 것입니다.

지침 관리의 선택지가 늘어난 업데이트입니다

이번 변화는 여러 AI 코딩 도구에서 이미 AGENTS.md 를 관리하는 팀에 유용할 수 있습니다. 조건에 맞는 프로젝트라면 Claude Code용 지침을 따로 중복 작성해야 하는 부담을 줄일 여지가 있습니다.

다만 같은 파일을 읽는다고 모든 도구가 지침을 똑같이 해석하거나 같은 결과를 내는 것은 아닙니다. 문서 한 장이 보안·품질·권한 관리를 대신하지도 않습니다.

핵심은 파일을 무조건 통합하는 것이 아니라 현재 구성을 유지하면서 새 선택지를 검토하는 데 있습니다. CLAUDE.md 유무와 플랫폼 예외를 확인한 뒤 실제 작업 기준에 맞는 프로젝트 지침을 운영하는 편이 좋습니다.

한 줄 요약: Claude Code는 프로젝트에 CLAUDE.md 가 없을 때 AGENTS.md 를 대신 읽으며, 적용 전 /config 설정과 플랫폼 예외를 확인해야 합니다.

참고 출처

• Anthropic 공식 GitHub: Claude Code 2.1.277 릴리스
• Claude Code 공식 변경 기록 확인하기

공식 변경 기록의 2026년 9월 18일 업데이트 기준입니다. 플랫폼 지원 예외도 해당 발표 시점을 기준으로 설명했습니다.