Claude Code·Codex·Gemini CLI를 섞어 쓰는 저장소라면 결론부터 말한다. 공통 규칙은 AGENTS.md 하나에 넣고, 저장소에서 CLAUDE.md는 빼라. Claude Code가 2026년 9월 18일 v2.1.277부터 CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 자동으로 읽기 시작했기 때문에, 같은 내용을 두 파일로 복사해 두던 시대는 끝났다. Codex와 Cursor·GitHub Copilot·OpenCode는 이미 AGENTS.md를 읽는다. 예외는 Gemini CLI뿐인데, 이것도 설정 한 줄로 해결된다. 이 글은 5개 도구의 공식 문서를 2026년 9월 23일 기준으로 전부 재확인해서, 어느 도구가 어느 파일을 언제 읽는지, 그리고 지금 있는 CLAUDE.md를 삭제할지 import로 남길지를 판정하는 실무 가이드다.
핵심 요약 — 30초 결론
- 기본값 동작: 저장소 어디에도(상위 디렉터리 포함) CLAUDE.md 계열 파일이 없어야 Claude Code가 AGENTS.md를 읽는다. 둘 다 있으면 CLAUDE.md만 읽고 AGENTS.md는 무시된다.
- CLAUDE.local.md 함정: gitignore된 개인 메모용 CLAUDE.local.md 하나를 추가하는 순간 AGENTS.md는 읽히지 않는다. 가장 흔한 “규칙을 고쳤는데 왜 안 지키지”의 원인이다.
- 첫 세션 함정: AGENTS.md 지원 버전으로 업그레이드한 직후의 첫 세션(짧은 -p 실행 포함)에서는 feature flag가 아직 내려오지 않아 안 읽힐 수 있다. 두 번째 세션부터 판단한다.
- 읽지 못하는 환경: Amazon Bedrock, Google Vertex AI, Microsoft Foundry, 텔레메트리 비활성화 세션에서는 AGENTS.md를 직접 읽지 못한다. 이때만 @AGENTS.md import가 든 CLAUDE.md를 유지한다.
- 5개 도구 최종 상태: 공용 규칙은 AGENTS.md 하나. Claude 전용 규칙이 필요하면 @AGENTS.md로 시작하는 CLAUDE.md. Gemini CLI는 settings.json에 파일명 배열 한 줄.
왜 지금 확인해야 하나
9월 18일 이전에는 Codex·Cursor용으로 AGENTS.md를 쓰는 팀도 Claude Code를 위해 CLAUDE.md를 옆에 두어야 했다. 내용을 복제하거나, @AGENTS.md import 한 줄을 넣거나, 심볼릭 링크를 거는 식이었다. 이 발표 관련 해커뉴스 스레드는 739포인트·286댓글에 달했고, 토론의 대부분은 “각자 어떤 우회책을 써 왔는가”였다.
문제는 검색해서 나오는 한국어 가이드 상당수가 아직 우회책 시대 정보라는 점이다. 8월 30일자 글은 “Claude Code는 CLAUDE.md만 읽고 AGENTS.md는 읽지 않는다(공식 문서)”라고 안내한다 — 9월 18일에 뒤집힌 내용이다. 2025년 11월자 글은 이제 불필요해진 Gemini CLI·Codex 설정 파일 세팅을 여전히 권고한다. 이 글은 실행 당일 기준으로 공식 문서를 다시 읽고 정리했다.
5개 도구가 실제로 읽는 파일 — 공식 문서 기준
각 도구의 공식 문서를 2026년 9월 23일에 다시 확인했다. 표의 내용은 모두 1차 자료(공식 문서·공식 changelog) 기반이다.
| 도구 | 기본 읽는 파일 | 하위 디렉터리 중첩 | CLAUDE.md | 비고 |
|---|---|---|---|---|
| Claude Code ≥ 2.1.277 | AGENTS.md (CLAUDE.md 계열이 경로에 없을 때) | 해당 디렉터리 파일을 열 때 | 최우선 | 4가지 모드로 변경 가능. Bedrock/Vertex/Foundry는 지원 안 함 |
| OpenAI Codex CLI | AGENTS.md (기본, 즉시) | 루트→작업 디렉터리, 디렉터리당 1개 | 읽지 않음 | 전역 ~/.codex/AGENTS.md 먼저. 합계 32KiB 제한 |
| Gemini CLI | GEMINI.md (기본) | JIT 방식으로 스캔 | 공식 문서상 대안으로 허용 | settings.json context.fileName 배열로 AGENTS.md 추가 |
| Cursor | AGENTS.md + .cursor/rules | 지원, 더 구체적인 쪽 우선 | 문서화 안 됨 | 공식 문서가 AGENTS.md를 “간단한 대안”으로 소개 |
| GitHub Copilot | AGENTS.md (저장소 어디든) | 가장 가까운 파일 우선 | 루트 단일 파일 허용 | .github/copilot-instructions.md는 별도 메커니즘 |
출처: 각 도구 공식 문서 (2026-09-23 확인)
여기서 눈여겨볼 두 가지.
Codex는 CLAUDE.md를 전혀 읽지 않는다. CLAUDE.md에만 있는 규칙은 Codex에게 보이지 않는다. 같은 저장소에서 Codex와 Claude Code를 함께 썼다면 두 도구가 공통으로 보는 파일은 AGENTS.md뿐이었다. 이번 지원 added로 드디어 Claude Code도 그 파일을 기본으로 읽게 된 것이다.
OpenCode는 Claude Code와 정반대다. OpenCode는 AGENTS.md를 먼저 읽고, AGENTS.md가 없을 때만 CLAUDE.md를 폴백으로 읽는다. 두 파일이 모두 있는 저장소에서 Claude Code는 CLAUDE.md를, OpenCode는 AGENTS.md를 읽는다. 내용이 다르면 두 에이전트가 서로 다른 규칙을 따르는데 어느 쪽도 그 사실을 알려주지 않는다.
Claude Code의 우선순위 규칙 — 어떤 파일이 ‘존재한다’로 세는가
Claude Code 공식 memory 문서가 정의하는 판정 규칙이다.
CLAUDE.md가 존재한다고 세는 파일 (이 중 하나라도 있으면 AGENTS.md를 읽지 않는다):
- 작업 디렉터리와 모든 상위 디렉터리의
CLAUDE.md - 같은 위치의
.claude/CLAUDE.md - 같은 위치의
CLAUDE.local.md
세지 않는 파일 (AGENTS.md와 함께 계속 로드된다):
- 개인용
~/.claude/CLAUDE.md - 조직의 managed CLAUDE.md
.claude/rules/파일
이 구분이 중요한 이유는 “개인 전역 설정을 쓰고 있으면 AGENTS.md가 안 읽히는 것 아닌가” 하는 오해 때문이다. 그렇지 않다. ~/.claude/CLAUDE.md는 프로젝트 판정에 영향을 주지 않는다. 프로젝트 경로 안의 파일만 판정에 개입한다.
AGENTS.md가 읽혔는지 확인하는 가장 빠른 방법은 대화 상단의 안내 줄이다. agents-md: no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md 형태로 뜬다. 직접 로드된 AGENTS.md는 /memory나 /context의 Memory files 목록에 표시되지 않으므로, 이 줄이 없으면 읽히지 않은 것이다.
4가지 Project instructions 모드
/config의 Project instructions 설정으로 동작을 바꿀 수 있다. 프로젝트·로컬 설정 파일에서는 이 키가 무시되고 사용자(~/.claude/settings.json)·managed 설정에서만 적용된다는 점에 주의한다.
| 값 | 읽는 파일 | 쓸 때 |
|---|---|---|
claude-md-or-agents-md (기본값) | CLAUDE.md, 또는 없을 때 AGENTS.md | 설정 없이 둘 중 하나 관례만 쓸 때 |
claude-md-and-agents-md | 디렉터리별 둘 다 (CLAUDE.md 먼저) | AGENTS.md에 짧은 Claude 전용 CLAUDE.md를 더해 쓰거나 CLAUDE.local.md를 쓸 때 |
claude-md | CLAUDE.md만 | AGENTS.md가 다른 도구용이라 Claude를 헷갈리게 할 때 |
managed-only | 조직 managed 파일 + 자동 메모리만 | 잠긴 엔터프라이즈 세션 |
설정 파일 형태는 다음과 같다.
{
"pluginConfigs": {
"agents-md@builtin": {
"options": {
"instructionFiles": "claude-md-and-agents-md"
}
}
}
}Claude 전용 규칙이 정말 필요한 게 아니라면 claude-md-and-agents-md를 쓰기보다 기본값 그대로 두고 CLAUDE.md를 정리하는 쪽이 깔끔하다. 파일이 둘이면 언젠가 내용이 갈라진다.
직접 로드된 AGENTS.md가 CLAUDE.md와 다른 점
설정으로 읽힌 AGENTS.md는 CLAUDE.md를 완전히 대체하지 않는다. 공식 문서가 밝히는 차이는 세 가지다.
- InstructionsLoaded 훅: CLAUDE.md에서는 발생, 설정으로 직접 읽은 AGENTS.md에서는 발생하지 않는다. CLAUDE.md가 import한 AGENTS.md에 대해서는 발생한다.
--add-dir추가 디렉터리:CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD환경 변수와 함께 쓰면 추가 디렉터리의 CLAUDE.md는 로드되고 AGENTS.md는 로드되지 않는다.- 외부
@pathimport: CLAUDE.md는 저장소 밖 파일 import 시 승인을 요청하지만, AGENTS.md는 이미 승인된 경우에만 로드하고 프롬프트하지 않는다.
훅을 쓰는 자동화가 있다면 이 차이가 실질적으로 영향을 준다. 해당 없으면 체감 차이는 없다.
마이그레이션 판정 — CLAUDE.md를 삭제할지 import로 남길지
기존 상태별로 공식 문서가 권하는 처리 방법이 다르다. 3분기 매트릭스로 정리했다.
| 현재 상태 | 판정 | 이유 |
|---|---|---|
| AGENTS.md만 있음 + Claude Code 추가 | 아무것도 하지 마라 | 업그레이드 후 두 번째 세션부터 자동으로 읽는다 |
| 기존 CLAUDE.md에 Codex 추가 | AGENTS.md로 이름을 바꿔라 | Codex는 CLAUDE.md를 읽지 못한다 |
| 두 파일, 같은 내용 | CLAUDE.md 삭제 또는 @AGENTS.md 한 줄로 교체 | 중복은 수정 시 어긋난다 |
| 두 파일, 다른 내용, 둘 다 필요 | 기본값 유지 + CLAUDE.md는 @AGENTS.md import로 시작 | Claude 전용 규칙을 import 아래에 추가 |
| 개인 메모용 CLAUDE.local.md 사용 | claude-md-and-agents-md 설정 또는 메모를 ~/.claude/CLAUDE.md로 이동 | CLAUDE.local.md가 AGENTS.md 로드를 막는다 |
| Bedrock / Vertex / Foundry | @AGENTS.md가 든 CLAUDE.md 유지 | 이 환경은 AGENTS.md 직접 로드 불가 |
과거 우회책을 쓰고 있었다면 이렇게 정리한다. CLAUDE.md에 @AGENTS.md import가 들어 있으면 그대로 둬도 된다 — 어떤 모드에서든 파일을 두 번 읽지 않는다. “AGENTS.md를 읽으라”는 문장만 있는 CLAUDE.md는 삭제하거나 import 구문으로 바꾼다. AGENTS.md를 심볼릭 링크한 CLAUDE.md는 링크를 삭제해도 내용은 한 번만 읽힌다. SessionStart 훅으로 AGENTS.md를 출력하고 있었다면 훅을 제거한다 — 직접 로드가 되면 컨텍스트에 사본이 하나 더 생긴다.
권장 최종 구성
# AGENTS.md (저장소 루트)
## 공통 규칙
- 커밋 메시지는 Conventional Commits 형식
- PR 전에 npm test 실행
## Claude Code 전용 (필요할 때만 CLAUDE.md로 분리)Claude 전용 규칙이 필요할 때만 CLAUDE.md를 이렇게 만든다.
@AGENTS.md
## Claude Code
- src/billing/ 변경은 plan mode 사용import 아래에 Claude 전용 내용을 적으면 import된 파일이 먼저, 나머지가 그 뒤에 로드된다.
Gemini CLI — AGENTS.md를 읽게 하는 설정 한 줄
Gemini CLI는 소스 코드 수준에서 기본 컨텍스트 파일명이 GEMINI.md로 정의되어 있다. AGENTS.md를 읽게 하려면 .gemini/settings.json에 컨텍스트 파일명 배열을 지정한다.
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}배열로 지정하면 두 파일을 모두 로드하고, 파일명 우선순위대로 찾는다. 전역 ~/.gemini/GEMINI.md는 그대로 살아 있으니 개인 기본값을 유지하면서 프로젝트 단위로 AGENTS.md를 붙일 수 있다. Gemini CLI는 @file.md import도 지원하므로, GEMINI.md 하나만 쓰고 싶다면 @AGENTS.md import로 공용 규칙을 가져오는 방법도 있다.
Codex — 전역과 32KiB 제한
Codex의 지침 체인은 두 층이다. 전역은 ~/.codex/AGENTS.override.md가 있으면 그것만, 없으면 ~/.codex/AGENTS.md를 읽는다. 프로젝트에서는 저장소 루트부터 작업 디렉터리까지 내려가며 디렉터리당 최대 한 파일(AGENTS.override.md → AGENTS.md → fallback 파일명 순)을 읽고, 루트부터 순서대로 이어 붙인다. 나중에 오는 파일(작업 디렉터리에 가까운 파일)이 앞선 지침을 덮어쓴다.
합산 크기 제한이 project_doc_max_bytes로 32KiB 기본값이다. 모노레포에서 지침이 길어지면 잘리므로, 제한을 올리거나 중첩 디렉터리로 분할한다.
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536지침을 어디서 로드했는지 감사하려면 codex -c log_dir=./.codex-log으로 TUI 로그를 남기거나 세션 로그의 jsonl 파일을 확인한다.
AGENTS.md가 읽히지 않을 때 — 순서대로 확인하는 체크리스트
- 버전:
claude --version으로 2.1.277 이상인지 확인한다. 낮으면claude update다. - 상위 디렉터리 스캔: 작업 디렉터리 위 어딘가에 CLAUDE.md 계열 파일이 숨어 있으면 그것이 이긴다. 다음으로 찾는다.
- 업그레이드 직후라면: 두 번째 세션부터 판단한다. 첫 세션은 feature flag가 내려오지 않았을 수 있다.
- 세션 유형:
/config에 Project instructions 항목 자체가 없으면 그 세션은 AGENTS.md를 로드할 수 없는 유형이다(Bedrock, 텔레메트리 비활성화 등).@AGENTS.mdimport로 우회한다. - 읽히지 않는 파일명:
AGENTS.local.md,AGENTS.override.md,.agents/디렉터리 안의 파일은 Claude Code가 읽지 않는다.AGENTS.override.md는 Codex 전용 규칙이다. /memory로 확인하지 말 것: 직접 로드된 AGENTS.md는 거기 표시되지 않는다. 대화 상단의AGENTS.md loaded줄이나 에이전트에 대한 지침 인용 질문으로 확인한다.
AGENTS.md에 무엇을 쓸 것인가
공식 문서의 기준은 “매번 다시 설명하게 되는 것”이다.
- 같은 실수를 두 번째 저질렀을 때
- 코드 리뷰에서 Claude가 알았어야 할 것이 걸렸을 때
- 지난 세션에 쳤던 교정을 또 치고 있을 때
- 새 팀원이 생산성을 내려면 같은 맥락이 필요할 때
빌드 명령, 컨벤션, 프로젝트 구조, “항상 X를 하라”류 규칙 같은 매 세션 필요한 사실만 담는다. 다단계 절차나 코드베이스 일부에서만 중요한 내용은 스킬이나 경로 스코프트 규칙으로 옮긴다. 지침은 구체적이고 간결할수록 일관되게 따른다.
FAQ
AGENTS.md와 CLAUDE.md를 둘 다 두면 어떻게 되나?
기본값에서는 CLAUDE.md만 읽히고 AGENTS.md는 무시된다. 둘 다 읽게 하려면 Project instructions를 claude-md-and-agents-md로 바꾼다.
Claude Code만 쓰는데 바꿔야 하나?
아니다. CLAUDE.md를 그대로 쓰면 된다. 바꿀 이유가 없다. 다른 도구를 같이 쓰게 되는 순간부터 AGENTS.md가 의미를 갖는다.
하위 폴더의 AGENTS.md도 읽나?
Claude가 그 폴더의 파일을 Read 도구로 열 때 읽는다. 단, 그 하위 폴더에 CLAUDE.md 계열 파일이 없을 때만이다. Cursor는 하위 폴더 작업 전반에 적용되고, Codex는 작업 디렉터리까지의 경로 전체를 미리 읽는다 — 도구마다 시점이 다르다.
Codex는 CLAUDE.md를 읽나?
아니요, 전혀 읽지 않는다. Codex와 Claude Code가 같은 규칙을 보게 하는 유일한 방법은 AGENTS.md 한 곳에 규칙을 두는 것이다.
/init을 돌리면 어떻게 되나?
Claude Code의 /init은 기본적으로 CLAUDE.md를 생성한다. CLAUDE_CODE_NEW_INIT=1을 켜면 기존 AGENTS.md를 CLAUDE.md에 합치고 이후 CLAUDE.md가 우선한다. AGENTS.md를 단일 소스로 유지하려면 /init을 건너뛰거나 생성된 파일을 삭제한다. Codex와 OpenCode의 /init은 AGENTS.md를 생성·갱신하므로 충돌하지 않는다.
마이그레이션 후 검증은 어떻게 하나?
Claude Code는 다음 세션에서 /context를 실행해 CLAUDE.md가 Memory files에 나타나는지 확인한다(import 방식의 경우). AGENTS.md 직접 로드는 대화 상단 줄로 확인한다. Codex는 codex --ask-for-approval never "Summarize the current instructions."를 저장소 루트에서 실행해 전역→프로젝트 순서로 인용되는지 확인한다.
참고자료
- Claude Code 공식 문서 — Memory (CLAUDE.md / AGENTS.md): https://code.claude.com/docs/en/memory
- Claude Code Changelog v2.1.277: https://code.claude.com/docs/en/changelog
- OpenAI Codex — Custom instructions with AGENTS.md: https://learn.chatgpt.com/docs/agent-configuration/agents-md
- Gemini CLI — Provide context with GEMINI.md files: https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/gemini-md.md
- Cursor Docs — Rules: https://cursor.com/docs/rules
- GitHub Docs — Repository custom instructions for Copilot: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
- OpenCode Docs — Rules: https://opencode.ai/docs/rules/
- AGENTS.md 공식 사이트: https://agents.md/
- 해커뉴스 토론 (2026-09-19, 739pts): https://news.ycombinator.com/item?id=49760187
