코덱스에는 AGENTS.md, 클로드 코드에는 CLAUDE.md. 같은 내용을 두 파일에 복사해두고 계셨죠. 클로드 코드 AGENTS.md 지원이 들어가면서 이제 한 파일로 됩니다. 2026년 9월 18일에 2.1.277 버전부터 들어간 기능이에요. 발표 글은 오늘까지 조회 535만을 넘었습니다.
다만 조건이 하나 붙어요. 두 파일이 같이 있으면 CLAUDE.md가 이기고 AGENTS.md는 안 읽힙니다. 둘의 차이와 우선순위를 제 화면으로 보여드릴게요. 제 맥에서 폴더를 만들어 하나씩 눌러보고, 어느 쪽이 이기는지 화면으로 확인했어요!
AGENTS.md만 있으면 그걸 읽어요
실험용 폴더에 AGENTS.md 파일 1개만 뒀습니다. 규칙 2개를 적었어요. 답변 첫 줄에 표시를 붙이라는 것, 고객 전화번호를 화면에 그대로 쓰지 말라는 것.
제 맥에 깔린 건 2.1.278입니다.
클로드 코드 2.1.278 시작 화면. 대화 위에 agents-md: no CLAUDE.md found; AGENTS.md loaded: 뒤에 파일 경로가 표시돼 있다. 그 아래 파일을 읽지 말고 답하라고 물었더니 AGENTS.md 규칙 적용이라는 표시와 함께 규칙 두 가 지를 그대로 말한다
세션이 열리자마자 이 줄이 떴습니다.
agents-md: no CLAUDE.md found; AGENTS.md loaded: (파일 경로)
파일을 읽지 말라고 못을 걸어두고 규칙을 물었는데도 AGENTS.md 내용을 그대로 말합니다. 클로드가 도구로 파일을 열어본 게 아니라 세션 시작부터 지침으로 들어가 있다는 뜻이에요.
CLAUDE.md를 만들면 AGENTS.md는 빠져요
같은 폴더에 CLAUDE.md를 추가하고 다시 열었어요. 이번엔 안내 줄이 아예 안 뜨고, 규칙을 물으니 CLAUDE.md 쪽 답이 나왔습니다. 두 파일을 합쳐서 읽는 게 아니라 한쪽만 읽어요.
공식 문서 기준으로 이렇게 갈립니다.
- AGENTS.md만 있을 때: AGENTS.md를 읽어요
- CLAUDE.md도 있을 때: CLAUDE.md만 읽어요. 작업 폴더뿐 아니라 그 위 상위 폴더에 있는 것도 셈에 들어갑니다
- CLAUDE.md가 AGENTS.md를 불러오고 있을 때: CLAUDE.md를 읽고, 그 안에서 불러온 AGENTS.md가 같이 들어와요
여기서 헷갈리기 쉬운 게 하나 있어요. 개인 설정인 ~/.claude/CLAUDE.md와 회사에서 관리하는 CLAUDE.md, .claude/rules/ 파일은 이 셈에 안 들어갑니다. 그래서 개인 규칙 파일을 쓰고 계셔도 프로젝트에 CLAUDE.md만 없으면 AGENTS.md가 읽혀요.
네 가지 중에 고를 수 있어요
기본값이 마음에 안 들면 /config에서 Project instructions 설정을 바꾸면 됩니다. 선택지는 4개입니다.
클로드 코드 config 화면의 Project instructions 설정. 네 가지 선택지 claude-md, claude-md-or-agents-md, claude-md-and-agents-md, managed-only가 있고 claude-md-or-agents-md에 체크 표시가 붙어 있다. 위에는 각 값이 무엇을 읽는지 설명이 적혀 있다
- claude-md: 예전처럼 CLAUDE.md만 읽습니다
- claude-md-or-agents-md: 기본값이에요. CLAUDE.md가 없는 프로젝트에서만 AGENTS.md를 읽습니다
- claude-md-and-agents-md: 둘 다 읽어요. 이미 불러온 파일을 두 번 읽지는 않습니다
- managed-only: 프로젝트와 개인 지침을 버리고 회사가 관리하는 파일만 남깁니다
두 도구를 같이 쓰면서 규칙을 한 파일로 모으고 싶으면 둘 다 읽게 하는 설정보다 기본값 그대로 두고 CLAUDE.md를 지우는 쪽이 깔끔해요. 파일이 둘이면 언젠가 내용이 갈라지거든요.
안 될 때 볼 것
제가 처음에 테스트했을 때는 AGENTS.md가 안 읽혔어요. 터미널에서 이미 클로드 코드를 켜둔 채 그 안에서 또 띄웠더니, 예전 버전인 2.1.275로 실행됐던 겁니다. 버전을 다시 확인하고 열었더니 그제야 안내 줄이 떴어요.
- 버전을 먼저 보세요.
claude --version으로 2.1.277 이상인지 확인합니다. 저는 2.1.278에서 됐어요 - 안내 줄이 뜨는지 보세요. 읽혔으면 대화 위에
agents-md: no CLAUDE.md found; AGENTS.md loaded:1줄이 뜹니다. 이 줄이 없으면 안 읽힌 겁니다 - 상위 폴더를 확인하세요. 작업 폴더 위 어딘가에 CLAUDE.md가 있으면 그게 이깁니다
- 안 되는 환경도 있어요. 아마존 베드록을 쓰거나 텔레메트리를 꺼둔 세션에서는 AGENTS.md를 직접 못 읽어요. 그때는 CLAUDE.md에서 불러오는 방식으로 쓰면 됩니다
제 경우는 2.1.275로 열렸을 때 클로드가 규칙이 없다고 답했어요. 파일은 그 자리에 그대로 있었고요. 버전만 맞추니 같은 폴더에서 바로 읽혔습니다.
읽히지 않는 파일 이름 3개도 정해져 있습니다. AGENTS.local.md, AGENTS.override.md, .agents/ 폴더 안의 파일은 안 읽습니다.
그래서 뭘 하면 되나
코덱스나 커서를 같이 쓰시면 이제 규칙을 AGENTS.md 한 곳에 적고 CLAUDE.md는 지우세요. 클로드 코드만 쓰시면 지금처럼 CLAUDE.md를 쓰시면 되고, 바꿀 이유가 없습니다.
팀 저장소라면 한 가지 더 봐두세요. 저장소에 CLAUDE.md가 남아 있으면 AGENTS.md를 아무리 고쳐도 클로드 코드에는 안 들어갑니다. 파일이 둘 다 있는 저장소에서 "규칙을 고쳤는데 왜 안 지키지" 싶으면 십중팔구 이 경우예요!
규칙 파일에 뭘 적을지가 더 중요한데, 공식 문서는 "매번 다시 설명하게 되는 것"을 적으라고 해요. 같은 실수를 또 겪었을 때, 지난 세션에 쳤던 교정을 또 치고 있을 때가 적을 때입니다.
이런 걸 매주 하나씩 붙잡고 만져보는 자리가 지피터스 AI 스터디예요. 클로드 코드 주제도 입문부터 고급까지 열려 있습니다.
자주 묻는 질문
AGENTS.md와 CLAUDE.md를 둘 다 두면 어떻게 되나요?
기본 설정에서는 CLAUDE.md만 읽혀요. AGENTS.md는 무시됩니다. 둘 다 읽게 하려면 /config의 Project instructions를 claude-md-and-agents-md로 바꾸세요.
하위 폴더에 있는 AGENTS.md도 읽나요?
클로드가 그 폴더의 파일을 열 때 읽어요. 다만 그 하위 폴더에 CLAUDE.md 계열 파일이 없을 때만입니다.
제 계정 규칙 파일은 어떻게 되나요?
~/.claude/CLAUDE.md는 그대로 살아 있어요. 프로젝트에 CLAUDE.md가 있는지 없는지를 따질 때 개인 파일은 셈에 안 들어갑니다.
확인일: 2026년 9월 21일. 기능 발표는 앤트로픽 클로드 코드 팀의 9월 18일 X 게시물, 읽는 규칙과 설정값 네 가지는 클로드 코드 공식 문서에서 확인했어요. 화면은 같은 날 제 맥에서 클로드 코드 2.1.278로 실험용 폴더를 만들어 직접 캡처했고, 경로에 세션 정보가 있어 일부를 가렸습니다. 컴팩션이 컨텍스트에서 뭘 지우는지는 클로드 코드 컴팩션 글에 적어뒀어요.