CLAUDE.md·AGENTS.md·GEMINI.md 비교: 하나로 합치는 법

git 저장소의 AGENTS.md에 KIWI-42라는 코드워드를 적어 두고, Claude Code에 “지시받은 코드워드를 모두 말해 달라”고 물었습니다. AGENTS.md만 있을 때는 KIWI-42가 나왔어요.

그런데 같은 저장소에 개인용 CLAUDE.local.md(LIME-08)를 함께 두면 답은 LIME-08뿐이었습니다. AGENTS.md가 경고 없이 빠진 거죠.

Claude Code, Codex CLI, Gemini CLI를 함께 쓰면 지시 파일을 어떻게 둘지가 고민입니다. 제 결론은 AGENTS.md 하나를 정본으로 두는 겁니다.

Codex CLI는 기본으로 읽고, Claude Code(v2.1.277 이상)는 CLAUDE.md가 없으면 그대로 읽어요. CLAUDE.md가 꼭 필요하면 그 안에 @AGENTS.md 한 줄을 두고, Gemini CLI는 settings.json의 context.fileName에 AGENTS.md를 넣으면 됩니다.

다만 위처럼 파일 하나가 끼어들면 빠지는 함정이 있어서, 그 부분을 중심으로 정리했습니다.

2026년 9월 14일 Claude Code 공식 문서와 Codex CLI·Gemini CLI 공식 저장소를 기준으로 정리했고, 10월 2일 Windows 11 · PowerShell 5.1 테스트 환경에서 Claude Code 2.1.286과 Codex CLI 0.159.3으로 직접 확인했습니다. Claude Code 쪽은 10월 14일 2.1.296에서 다시 확인했습니다.

CLAUDE.md에 무엇을 적을지는 CLAUDE.md 작성법에서 다뤘고, 여기서는 세 도구 사이에서 파일을 어떻게 두느냐만 봅니다.

코드워드로 확인해 보니

지시 파일마다 서로 다른 코드워드를 한 줄씩 적고(AGENTS.md는 KIWI-42, CLAUDE.md는 MANGO-17처럼), 두 도구에 같은 질문을 했습니다. 파일을 열어 찾아보지 않고 답하게 했으니, 답은 시작할 때 읽어 들인 지시 파일만 반영합니다.

저장소에 둔 것	Claude Code	Codex CLI
AGENTS.md만	KIWI-42	KIWI-42
AGENTS.md + CLAUDE.md	MANGO-17	KIWI-42
AGENTS.md + CLAUDE.local.md(LIME-08)	LIME-08	—
CLAUDE.md만	—	NONE
CLAUDE.md만 + Codex 폴백에 CLAUDE.md	—	MANGO-17
AGENTS.md + CLAUDE.md + 같은 폴백	—	KIWI-42

AGENTS.md만 있으면 두 도구 모두 읽었습니다. 제가 AGENTS.md를 정본으로 권하는 근거가 이 첫 줄이에요. 나머지 줄은 아래 두 절에서 볼 함정을 그대로 보여 줍니다. 홈에는 두 도구의 전역 지시 파일(~/.claude/CLAUDE.md, ~/.codex/AGENTS.md)이 있었지만 코드워드가 없어 답에 영향을 주지 않았습니다.

도구별 기본 이름과 이름을 바꾸는 수단을 나란히 놓으면 이렇습니다.

도구	기본으로 읽는 파일	다른 이름을 읽게 하는 법
Claude Code	CLAUDE.md, CLAUDE.local.md(없으면 AGENTS.md)	/config → Project instructions, @AGENTS.md import
Codex CLI	AGENTS.override.md → AGENTS.md	project_doc_fallback_filenames
Gemini CLI	GEMINI.md	settings.json의 context.fileName

Gemini CLI는 context.fileName에 이름 하나 또는 목록을 받습니다. 공식 예시는 이래요.

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

그런데 이 설정은 GEMINI.md 문서에만 나오고, 같은 저장소의 설정 레퍼런스 Context 절(context.discoveryMaxDirs 등 일곱 항목)에는 없었습니다(2026년 9월 14일 기준).

CLAUDE.local.md 하나로 AGENTS.md가 빠진다

Claude Code는 v2.1.277부터 CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 대신 읽습니다. 헷갈리는 건 무엇을 “CLAUDE.md가 있다”로 세느냐예요.

작업 폴더와 그 위에 있는 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md는 셉니다. 반면 홈의 ~/.claude/CLAUDE.md, 조직의 관리형 CLAUDE.md, .claude/rules/ 파일은 세지 않고 AGENTS.md와 함께 로드됩니다.

그래서 위 표처럼 홈에 ~/.claude/CLAUDE.md가 있어도 AGENTS.md가 읽혔고, 저장소에 CLAUDE.local.md를 하나 두자 AGENTS.md가 빠졌습니다.

함정: 팀이 AGENTS.md를 쓰는 저장소에서 혼자 CLAUDE.local.md를 만들면, 팀 지시가 경고 없이 빠집니다.

10월 14일 Claude Code 2.1.296에서 표의 Claude Code 세 줄을 다시 물어도 KIWI-42, MANGO-17, LIME-08로 같았습니다. 빠진 게 눈에 보이는 곳은 /memory예요. AGENTS.md만 있을 때는 목록에 AGENTS.md가 있다가, CLAUDE.local.md를 두면 그 자리를 CLAUDE.local.md가 차지합니다.

둘을 함께 읽게 하려면 /config의 Project instructions를 바꾸면 됩니다. 고를 수 있는 값은 이렇습니다.

값	읽는 것
claude-md-or-agents-md(기본)	CLAUDE.md, 없으면 AGENTS.md
claude-md-and-agents-md	둘 다
claude-md	CLAUDE.md만
managed-only	관리형 지시만

claude-md-and-agents-md로 둘 다 읽게 해도 import나 심볼릭 링크로 이미 들어온 AGENTS.md는 다시 읽지 않습니다. 이름이 비슷한 AGENTS.override.md와 AGENTS.local.md는 읽지 않고, v2.1.277 이전 버전이나 내장 agents-md 플러그인을 끈 세션에서는 예전처럼 CLAUDE.md만 읽어요.

Codex CLI는 git 루트 위를 안 본다

Codex CLI는 먼저 프로젝트 루트를 정합니다. 현재 폴더에서 위로 올라가며 project_root_markers(기본값 .git)를 찾고, 루트에서 현재 폴더까지 내려오며 찾은 파일을 순서대로 이어 붙여요. 마커를 못 찾으면 현재 폴더만 보고, 마커 목록을 비우면 위로 찾지 않습니다. 루트 위로는 올라가지 않습니다.

폴더마다 후보는 AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames에 적은 이름 순이고, 처음 찾은 파일 하나를 읽으면 그 폴더에서는 멈춥니다.

폴백은 “함께 읽는 목록”이 아니라 “앞의 것이 없을 때 쓰는 이름”인 거죠. 위 표에서 폴백에 CLAUDE.md를 넣었는데도 AGENTS.md가 있는 폴더에서는 KIWI-42만 나온 이유입니다(폴백은 -c project_doc_fallback_filenames=["CLAUDE.md"]로 줬습니다).

참고로 저장소의 docs/agents_md.md는 외부 문서 페이지로 안내만 하는 짧은 파일이에요. 그래서 이 탐색 규칙은 구현 파일 codex-rs/core/src/agents_md.rs의 모듈 주석과 후보 이름 처리 코드를 근거로 했고, 10월 2일 직접 실행으로 확인했습니다.

범위 차이도 직접 확인했습니다. 저장소 바깥 상위 폴더에 CLAUDE.md(PEAR-33)와 AGENTS.md(PLUM-55)를 더 두고 같은 질문을 했더니 이렇게 갈렸어요.

Claude Code: PEAR-33, MANGO-17
Codex CLI:   KIWI-42

Claude Code는 저장소 위 폴더의 CLAUDE.md까지 읽었고, Codex CLI는 .git이 있는 루트에서 멈췄습니다. 세 도구의 범위를 한 그림에 모으면 이렇습니다.

Claude Code는 시작할 때 현재 폴더와 그 위 모든 폴더의 CLAUDE.md·CLAUDE.local.md를 읽고, 하위 폴더 파일은 그 폴더의 파일을 읽을 때 포함합니다. Gemini CLI는 홈의 ~/.gemini/GEMINI.md(전역), 워크스페이스와 그 상위 폴더를 읽고, 도구가 어떤 파일을 다룰 때 그 폴더와 조상을 신뢰 루트까지 다시 훑어요.

--add-dir처럼 추가로 연 폴더는 Claude Code와 Gemini CLI 둘 다 기본으로 안 읽습니다. Claude Code는 --add-dir로 연 폴더의 CLAUDE.md를 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD를 켜야 읽고, Gemini CLI의 context.loadMemoryFromIncludeDirectories도 기본값이 false입니다.

import냐 심볼릭 링크냐

상황별로는 이렇게 두시길 권합니다.

상황	두는 방법
AGENTS.md를 쓰는 저장소 + Claude Code	CLAUDE.md를 두지 않음
Claude 전용 지시도 필요	CLAUDE.md 첫 줄에 @AGENTS.md
세 도구 모두	위 + Gemini context.fileName에 AGENTS.md
저장소 바깥 공통 규칙	저장소 안으로 옮기기(Codex 때문)

Claude Code는 CLAUDE.md 안의 @AGENTS.md 한 줄로 다른 파일을 펼쳐 넣고, Gemini CLI도 @file.md 문법으로 상대·절대 경로의 파일을 가져옵니다. v2.1.277 이전 Claude Code를 함께 쓰는 사람이 있어도 import는 동작해요.

ln -s AGENTS.md CLAUDE.md 한 줄로 끝내는 방법도 있습니다. macOS·Linux만 쓴다면 읽기는 돼요.

하지만 Windows가 끼면 얘기가 달라집니다. 심볼릭 링크를 만들려면 관리자 권한이나 개발자 모드가 필요하고, core.symlinks가 꺼져 있으면 Git이 링크를 한 줄짜리 텍스트 파일로 체크아웃하거든요.

그 클론의 CLAUDE.md는 지시 대신 경로 한 줄이 됩니다. 그래서 Claude Code 문서도 Windows 사용자가 있으면 import를 쓰라고 안내해요.

편집도 걸립니다. Claude Code의 Edit·Write 도구는 링크를 통한 쓰기를 거부하고 링크 대상을 고치라고 안내합니다. 아래 Refusing to write through symlink 오류가 그거예요.

세 파일을 모두 두면 내용이 중복으로 들어가는지는 도구마다 다릅니다. Claude Code는 기본값에서 CLAUDE.md가 있으면 AGENTS.md를 읽지 않고, GEMINI.md는 읽는 파일로 꼽지 않아요.

Codex CLI는 한 폴더에서 후보 하나만 읽습니다. Gemini CLI는 한 폴더에 context.fileName의 이름이 여럿 있을 때의 동작이 문서에 없고요.

그래서 저는 내용이 겹치는 파일을 여러 개 두기보다 정본 하나를 가져오게 하는 쪽을 권합니다.

이미 다른 도구 설정이 있는 저장소라면 Claude Code의 /import(v2.1.213 이상)가 AGENTS.md 같은 지시 파일 사본을 CLAUDE.md에 덧붙이고 MCP 서버·명령·서브에이전트·스킬도 함께 옮깁니다.

/init는 기본으로 Cursor 규칙(.cursor/rules/, .cursorrules)과 Copilot 규칙(.github/copilot-instructions.md)을 읽고, CLAUDE_CODE_NEW_INIT=1을 켜면 AGENTS.md, .devin/rules/, .windsurf/rules/·.windsurfrules, .clinerules까지 읽어요.

합쳤는데 안 읽힐 때

먼저 지시 파일이 실제로 읽혔는지부터 확인하세요. Claude Code는 /context의 Memory files 목록에서 CLAUDE.md를, /memory 목록에서 직접 읽힌 AGENTS.md 항목을 봅니다(v2.1.280 이전에는 둘 다 AGENTS.md를 표시하지 않았습니다).

Gemini CLI는 /memory show와 푸터의 파일 개수로 봐요. Codex CLI는 위처럼 코드워드를 한 줄 적어 두고 물어보는 방법이 가장 확실했습니다.

Refusing to write through symlink

심볼릭 링크로 만든 CLAUDE.md를 Claude Code가 읽기는 하는데 고치지 못하는 경우입니다.

Error: Refusing to write through symlink: <링크로 만든 CLAUDE.md 경로>. Resolve the symlink and pass the real target path explicitly.

정해진 동작이에요. 링크를 따라 읽기는 하지만 Edit·Write는 링크를 통해 쓰지 않고, 링크 대상(AGENTS.md)을 고치도록 안내합니다(2026년 9월 28일 문서 기준, 설계 이유는 문서에 없음).

대상 파일 AGENTS.md를 직접 고치거나, 링크 대신 @AGENTS.md import로 바꾸세요. import면 CLAUDE.md가 진짜 파일이라 이 오류가 나지 않습니다.

Gemini CLI: context.fileName을 바꿨는데 컨텍스트가 비어 있다

/memory show로 지금 불러온 메모리 전체를 보고, /memory reload로 설정된 위치를 다시 훑어 보세요. CLI 푸터에도 불러온 컨텍스트 파일 개수가 나옵니다.

비어 있으면 파일 위치보다 이름 설정이 적용됐는지부터 의심하는 게 좋아요. 같은 증상의 공개 보고가 있지만 원인은 밝혀지지 않았습니다(아래 사례).

Codex CLI가 상위 폴더의 AGENTS.md를 안 읽는다

기본 마커 .git 때문에 저장소 루트가 탐색의 끝이라서입니다. 같은 파일을 Claude Code는 작업 폴더와 그 위에 CLAUDE.md류가 없으면 읽어요.

공통 규칙을 저장소 안으로 옮기거나, project_root_markers를 상위 폴더에만 있는 표식으로 바꿔 루트를 올리면 됩니다. 기본 목록에 .git이 있으니 표식만 추가하면 저장소 루트가 먼저 걸려 소용없어요.

다른 사람들이 겪은 문제

이름을 하나로 모으려다 막힌 기록들입니다. 아래 네 건은 다른 사람들이 공개한 기록입니다.

• bbiggs는 Gemini CLI가 AGENTS.md를 기본으로 읽게 해 달라고 요청했고(2025-10-31, #12345), 원치 않는 사용자를 위해 목록에서 빼는 방법도 함께 필요하다고 적었습니다. 계획 없음으로 닫혔습니다.
• DylanLIiii는 Claude Code에 같은 요청을 올렸습니다(2025-08-21, #6235). 다른 도구들이 AGENTS.md로 모이는데 CLAUDE.md는 Claude Code 전용이라 협업에 맞지 않는다는 이유였고, v2.1.277에서 CLAUDE.md가 없을 때 AGENTS.md를 읽는 기능이 들어왔습니다.
• robertwt7은 Gemini CLI 0.29.5(macOS)에서 context.fileName에 AGENTS.md를 포함한 세 이름을 적고 루트에 AGENTS.md를 뒀는데 감지되지 않고 /memory show도 비어 있었다고 보고했습니다(2026-02-22, #19872). 원인은 적혀 있지 않고 계획 없음으로 닫혔습니다.
• imih는 Claude Code 2.1.168(Ubuntu/Debian)에서 ln -s AGENTS.md CLAUDE.md 뒤 읽기는 되지만 Edit·Write가 거부된다고 보고했습니다(2026-06-09, #66559). 이전 버전에서는 됐다는 회귀 표시를 달았고, 대상인 AGENTS.md를 고치면 성공한다고 적었습니다.

마치며

코드워드로 하나씩 확인해 보니, 세 도구가 지시 파일을 읽는 규칙은 “이름”보다 “무엇이 함께 있느냐”와 “어디까지 올라가느냐”에서 갈렸습니다. 개인용 CLAUDE.local.md 하나가 팀의 AGENTS.md를 밀어내고, 저장소 바깥에 둔 공통 규칙은 Codex CLI만 못 읽었어요. 둘 다 경고는 없었습니다.

그래서 저는 AGENTS.md 하나를 저장소 안에 정본으로 두고, Claude 전용 지시가 필요할 때만 CLAUDE.md에 @AGENTS.md를 두는 쪽을 권합니다. 지금 저장소 루트에 CLAUDE.md·CLAUDE.local.md·AGENTS.md가 각각 있는지 한 번 확인해 보세요.

지시 파일을 맞췄다면 다음 차이는 권한과 샌드박스이니, Claude Code·Codex·Gemini CLI 샌드박스 비교를 이어서 읽으시면 됩니다.