Anthropic의 코딩 도구 Claude Code가 버전 2.1.277부터 AGENTS.md를 지원한다. 규칙은 간단하다. 어떤 폴더에 CLAUDE.md가 없으면 Claude Code는 같은 폴더 안의 AGENTS.md를 찾아 프로젝트 지침으로 컨텍스트에 읽어들인다. CLAUDE.md가 있는 폴더는 예전처럼 CLAUDE.md만 참조한다.
이번 버전은 9월 18일 GitHub에 공개됐다. Claude Code 팀 소속 Thariq는 소셜미디어에서 이 변경 사항을 알렸다.
Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.
오늘 배포된 2.1.277 버전부터, 폴더에 CLAUDE.md가 없으면 Claude가 AGENTS.md를 찾아 사용한다는 내용이다.
네 단계 전환
AGENTS.md 지원은 내장 플러그인 형태로 구현됐고, 코드는 Claude Code GitHub 저장소에 공개돼 있다. 사용자는 /config의 'Project instructions'에서 전환할 수 있으며 모드는 총 네 가지다.
| 모드 | 동작 |
|---|---|
| claude-md | CLAUDE.md만 읽는다. 사실상 이 기능을 끄는 것과 같다 |
| claude-md-or-agents-md (기본값) | 같은 폴더에 CLAUDE.md가 있으면 그 폴더의 AGENTS.md는 무시하고, 없을 때만 AGENTS.md를 읽는다 |
| claude-md-and-agents-md | 디렉터리 트리 전체에서 두 파일을 모두 읽는다 |
| managed-only | 저장소에 커밋된 지침 파일과 개인용 지침 파일을 모두 버리고, 조직이 일괄 배포한 파일과 메모리만 남긴다 |
기본 모드는 '폴백'이지 '병합'이 아니다. 이미 Claude Code용 CLAUDE.md를 갖춘 저장소는 업그레이드 후에도 동작이 그대로다. CLAUDE.md를 한 번도 작성한 적 없이 다른 도구를 위해 AGENTS.md만 준비해 둔 저장소만 이번에 처음으로 이 파일을 읽어들이게 된다. 경로나 내용이 중복으로 판정된 동일 파일은 두 번 로드되지 않는다.
CLAUDE.md와 아직 다른 몇 가지
플러그인 문서에는 CLAUDE.md와의 차이점이 몇 가지 나와 있다. 하위 디렉터리의 AGENTS.md는 Agent가 Read 도구로 해당 디렉터리의 텍스트 파일을 읽을 때만 함께 불러온다. IDE 선택 영역, 노트북, 이미지, PDF는 이를 유발하지 않는다. 이렇게 불러온 파일은 '읽음' 상태로 기록되지 않아 컨텍스트 압축 후에도 자동으로 복원되지 않는다. /memory 명령과 # 단축 메모리도 AGENTS.md를 건드리지 않으며, --add-dir로 추가한 디렉터리도 AGENTS.md를 제공하지 않는다. 심볼릭 링크 경로는 해석되지 않고 문자열 그대로 비교된다.
채널 면에서는 AWS Bedrock, Google Vertex, Microsoft Foundry가 아직 지원되지 않는다. 같은 버전에는 지침 파일과 관련한 또 다른 변경도 있다. SDK와 헤드리스 모드로 시작할 때 첫 턴에서 더 이상 CLAUDE.md 조회가 끝나기를 기다리지 않는다.
저장소 하나, Agent 여럿
AGENTS.md는 코딩 Agent를 위한 README라고 할 수 있다. 빌드 방법, 테스트 실행 방법, 코드 스타일 규칙, 건드리면 안 되는 디렉터리 같은 내용을 담는다. 이 포맷은 2025년 OpenAI Codex 등 여러 도구가 함께 밀었고, 이후 리눅스 재단 산하 Agentic AI Foundation으로 관리가 넘어갔으며 Cursor, GitHub Copilot 등에서도 인식한다. Claude Code는 그동안 자체 CLAUDE.md만 인식해, 여러 도구를 섞어 쓰는 팀은 거의 같은 내용의 파일 두 개를 유지해야 했다. 심볼릭 링크로 두 파일을 같은 파일에 연결해두는 것이 흔한 우회법이었다.
중국 내 팀은 도구 조합이 더 다양한 편이다. Claude Code 외에 Kimi Code, Qwen Code, Cursor, Codex를 함께 쓰는 경우가 흔한데, 이 중 상당수가 기본적으로 AGENTS.md를 읽거나 지침 파일 이름을 바꿀 수 있게 해준다. 기본 모드에서는 기존 저장소를 한 줄도 고칠 필요가 없다. AGENTS.md 하나만 유지하고 싶은 팀은 CLAUDE.md를 지우고 지침을 그쪽으로 모을 수 있지만, 그 전에 위의 제약, 특히 긴 세션이 압축된 뒤 하위 디렉터리 지침이 자동으로 돌아오지 않는다는 점을 먼저 확인해야 한다.
managed-only 모드는 기업 관리자를 위한 것이다. 저장소에 커밋된 지침 파일은 Agent가 지침으로 실행하기 때문에 그 자체로 오염될 수 있는 입구가 된다. 관리자는 이 모드로 조직이 일괄 배포한 규칙만 허용할 수 있다. 대규모 팀에서 이 모드가 실제로 얼마나 잘 작동하는지에 대한 공개 데이터는 아직 없다.
참고 출처: Claude Code GitHub 릴리스 노트, CocoLoop, Anthropic 엔지니어 Thariq의 공개 게시물; agents-md 플러그인 문서로 네 가지 모드, 로드 순서, 제약 사항을 확인했다.