AI 코딩 에이전트를 실무에 붙일 때 가장 먼저 부딪히는 문제는 "이 저장소에서 지켜야 할 규칙을 도구에게 어떻게 알려줄 것인가"이다. 빌드·테스트 명령, 코드 스타일, 디렉터리 구조, 넘지 말아야 할 경계 같은 정보를 매번 대화창에 입력할 수는 없기 때문이다. Claude Code는 이를 위해 저장소에 놓인 CLAUDE.md라는 지침 파일을 자동으로 읽어 맥락으로 삼는 방식을 써 왔다. 이번 변경 사항의 핵심은 간단하다. 프로젝트에 CLAUDE.md가 존재하지 않을 경우, Claude Code가 대신 AGENTS.md 파일을 읽어들이도록 동작이 확장됐다는 것이다.
왜 이 작은 변화가 의미를 갖는가
표면적으로는 파일 이름 하나를 더 인식하는 사소한 개선처럼 보인다. 그러나 이 변화가 주목받는 이유는 AGENTS.md라는 이름 자체에 있다. AGENTS.md는 특정 벤더의 도구에 종속되지 않는, 여러 AI 코딩 에이전트가 공통으로 참조하도록 하자는 취지에서 확산되어 온 명명 규약이다. 즉 Claude Code가 이 파일을 인식하기 시작했다는 것은, 자사 고유 포맷만 고집하지 않고 도구 중립적인 지침 파일 관례에 발을 맞췄다는 신호로 읽힌다.
실무 관점에서 이 조합이 만들어내는 효과는 분명하다. 하나의 저장소를 여러 종류의 에이전트나 팀원이 함께 다루는 환경에서는, 도구마다 별도의 규칙 파일을 만들고 동기화하는 부담이 컸다. 같은 내용을 여러 파일에 중복해 두면 한쪽만 수정되어 지침이 서로 어긋나는 일도 잦았다. AGENTS.md를 공용 지침 파일로 두면 Claude Code를 포함한 여러 도구가 같은 문서를 바라보게 할 수 있어, 유지보수 지점을 하나로 줄일 여지가 생긴다.
우선순위를 이해하는 것이 관건
다만 이번 동작에서 반드시 짚어야 할 지점은 "없을 때"라는 조건이다. AGENTS.md는 CLAUDE.md가 존재하지 않을 때 비로소 읽히는 대체 경로다. 따라서 저장소에 이미 CLAUDE.md가 있다면 그 파일이 여전히 우선한다고 이해하는 편이 안전하다. 두 파일을 동시에 두고 병합을 기대하기보다는, Claude Code에만 특화된 지침이 필요할 때 CLAUDE.md를 쓰고 도구 공통 규칙은 AGENTS.md에 모으는 식으로 역할을 나누는 접근이 혼란을 줄인다.
한국의 개발 조직에서도 활용 시나리오는 어렵지 않게 그려진다. 사내 표준 빌드 절차나 커밋 규칙, 금지된 라이브러리 목록 같은 항목을 AGENTS.md 한 곳에 정리해 두면, 팀원마다 다른 에이전트를 쓰더라도 같은 기준선에서 출발할 수 있다. 기존에 CLAUDE.md로 관리하던 프로젝트라면 당장 바꿀 필요는 없지만, 새 저장소를 시작하거나 여러 도구를 병행하는 상황이라면 처음부터 공용 규약 파일을 채택하는 선택지가 생긴 셈이다.
남는 물음과 한계
공개된 릴리스 노트 수준의 정보만으로는 아직 구체적인 동작 범위를 단정하기 어렵다. 어느 디렉터리 계층까지 파일을 탐색하는지, 두 파일이 모두 존재하는 특수한 경우의 처리 방식, 파일 내부에서 지원되는 문법의 범위 같은 세부는 이번 언급만으로는 확인되지 않는다. 실제 도입에 앞서 소규모 저장소에서 파일을 어떻게 인식하고 지침을 어느 정도까지 반영하는지 직접 테스트해 보는 편이 바람직하다.
그럼에도 이 변화가 시사하는 방향성은 뚜렷하다. 에이전트에게 프로젝트 규칙을 전달하는 지침 파일이 특정 도구의 전유물이 아니라 저장소가 공유하는 자산으로 자리잡아 가고 있다는 점이다. 도구를 갈아타거나 여러 에이전트를 함께 굴리는 일이 잦아질수록, 규칙을 한 곳에 모아 두는 관행의 가치는 더 커질 것이다.