Gemini CLI 컨텍스트 파일: GEMINI.md를 어디에 두면 읽히나

여러 저장소에 같은 규칙을 쓰고 싶어서, 저장소들을 모아 둔 상위 폴더에 GEMINI.md를 하나 두는 경우가 있습니다. 그런데 Gemini CLI는 기본 설정으로는 그 파일을 읽지 않아요. 위로 올라가며 찾는 탐색이 .git이 있는 저장소 루트에서 멈추거든요.

이 규칙과 예외가 공식 문서 여러 곳에 흩어져 있어서, 파일을 어디에 둬야 하는지 한 번에 보기가 어렵습니다.

자리는 이렇게 나누면 됩니다. 모든 프로젝트에 쓸 지시는 ~/.gemini/GEMINI.md에, 저장소 전체에 쓸 지시는 저장소 루트의 GEMINI.md에 둡니다.

Gemini CLI는 이 파일들과 하위 폴더의 GEMINI.md를 모두 이어 붙여 매 요청에 함께 보내고, 무엇이 읽혔는지는 대화 화면에서 /memory list로 확인해요. 컨텍스트 파일은 에이전트에게 매번 같은 말을 반복하지 않으려고 미리 적어 두는 마크다운 파일입니다.

시작하기 전에 계정부터 확인하세요. 2026년 6월 18일부터 Gemini CLI는 무료로 쓰는 사용자와 Google AI Pro·Ultra 구독자의 요청을 처리하지 않습니다(메인테이너 Dmitry Lyalin, 2026년 5월 19일 공식 저장소 토론 글).

조직이 Gemini Code Assist Standard·Enterprise 라이선스나 Google Cloud로 쓰는 경우, 유료 Gemini API 키와 Gemini Enterprise Agent Platform API 키는 계속 쓸 수 있어요.

개인 무료·AI Pro·Ultra 계정이라면 이 글의 /memory 확인을 해 볼 세션 자체가 열리지 않을 수 있으니 Windows에서 Antigravity CLI(agy)를 설치하고 Gemini CLI 설정·GEMINI.md를 옮기는 순서부터 보세요. Antigravity CLI도 GEMINI.md를 그대로 읽습니다.

2026년 9월 17일 Ubuntu 24.04 · Gemini CLI 0.60.0(npm) 테스트 환경에서 확인했고, 공식 문서도 같은 날 다시 봤습니다. 파일이 실제로 어떤 순서로 로드되는지는 로그인해야 열리는 대화형 화면에서만 보여서, 로드 결과 화면은 싣지 않았습니다.

세 곳의 GEMINI.md는 전부 이어 붙는다

~/work/repo/app에서 gemini를 실행했다고 해 봅시다. 홈의 ~/.gemini/GEMINI.md, 저장소 루트의 ~/work/repo/GEMINI.md, 실행한 폴더의 repo/app/GEMINI.md가 모두 이어 붙어 시스템 프롬프트에 들어가고 매 요청에 함께 갑니다. 우선순위가 높은 파일 하나만 고르는 방식이 아니에요.

단계	위치	적용 범위
전역	~/.gemini/GEMINI.md	모든 프로젝트
작업 폴더와 상위	현재 폴더부터 저장소 루트까지	저장소 전체 또는 일부
더 좁은 범위	하위 폴더	특정 모듈·컴포넌트

두 번째 단계는 현재 작업 폴더에서 부모 폴더로 올라가며 찾다가, .git 폴더가 있는 프로젝트 루트나 홈 폴더 중 먼저 만나는 곳에서 멈춥니다. 글 처음에 말한 상위 폴더의 공통 파일이 기본 설정으로 읽히지 않는 이유가 이거예요.

이어 붙일 때는 파일마다 출처와 경로를 표시하는 구분자가 붙습니다.

그런데 좁은 범위의 파일이 넓은 범위의 파일을 이기는지는 보장되지 않아요. 공식 문서도 좁은 쪽이 넓은 쪽을 “대개” 덮거나 보충한다고만 설명합니다. 항상이 아니라 보통이라는 뜻이죠.

실제로 어떻게 합쳐졌는지는 /memory show로 봅니다.

주의: 서로 부딪히는 규칙을 여러 파일에 나눠 적으면 어느 쪽을 따를지 보장되지 않으니, 그런 규칙은 한 파일에서 정리하세요.

전역 파일 하나에 다 몰아 적는 것도 저는 권하지 않습니다. 전역 파일은 모든 프로젝트에 붙기 때문에, 특정 저장소의 빌드 명령이나 코드 규칙을 넣으면 다른 프로젝트에서 엉뚱한 지시가 돼요. 커질수록 프로젝트마다 어긋나는 문장도 늘어나고요.

전역 파일에는 특정 언어·도구에 묶이지 않는 개인 선호만 두고, 저장소 규칙은 저장소 루트에 두고 팀과 함께 커밋하는 편이 낫습니다.

저장소 바깥 파일을 읽히려면

위쪽 탐색이 .git에서 멈추는 건 설정 context.memoryBoundaryMarkers의 기본값이 [".git"]이기 때문입니다. 이 표식 중 하나가 있는 첫 폴더에서 멈추고, 배열을 비우면 위쪽 탐색이 아예 꺼져요.

여러 저장소가 공통 규칙을 나눠 쓰게 하는 방법은 셋입니다.

하고 싶은 것	설정
저장소 루트보다 위까지 탐색	context.memoryBoundaryMarkers를 상위 폴더에만 있는 표식으로 바꿈
다른 폴더를 작업 공간에 더하기	context.includeDirectories에 경로 추가(기본값 [])
더한 폴더의 GEMINI.md도 읽기	context.loadMemoryFromIncludeDirectories를 true로(기본값 false)

함정은 마지막 줄입니다. 폴더를 작업 공간에 더하는 것과 그 폴더의 지시 파일을 읽는 것은 별개의 스위치라서, 두 번째 줄만 하면 지시 파일은 읽히지 않아요. context.includeDirectories에 존재하지 않는 폴더를 적으면 경고와 함께 건너뜁니다.

경계 표식을 바꿀 때도 하나 조심하세요. 기본값의 .git을 남긴 채 표식을 더하기만 하면 저장소 루트에서 먼저 멈추니까 경계가 올라가지 않습니다.

저는 설정을 건드리기보다 공통 규칙 파일을 저장소 안으로 옮기고 @경로.md로 가져오는 쪽이 덜 헷갈린다고 봐요. 가져오기는 아래 “@로 쪼개기”에 있습니다.

하위 폴더 규칙은 언제 붙나

여기는 공식 문서 두 곳의 설명이 다릅니다. 둘을 억지로 맞추지 않고 그대로 옮길게요.

문서	부르는 이름	언제 훑나
docs/cli/gemini-md.md	JIT(필요할 때) 컨텍스트	도구가 그 파일·폴더에 접근할 때 그 자리에서
docs/reference/configuration.md	하위 디렉터리 컨텍스트	현재 폴더 아래를 미리, 기본 200개 폴더까지

설정 레퍼런스 쪽 방식이라면 node_modules·.git 같은 흔한 무시 패턴은 건너뛰고, 훑는 폭은 context.discoveryMaxDirs로 정합니다.

어느 쪽으로 도는지는 로그인한 대화형 화면에서 /memory list로 확인하세요. 세션을 막 시작했을 때 하위 폴더의 GEMINI.md가 목록에 없다면, 그 규칙은 그 폴더를 건드리기 전까지 붙지 않는 겁니다.

그래서 세션 시작부터 꼭 적용돼야 하는 규칙은 저장소 루트나 작업 폴더에 두시길 권합니다.

이름 바꾸기와 파일 쪼개기

다른 이름 쓰기

기본 이름은 GEMINI.md이고, context.fileName에 문자열 하나나 배열로 바꿉니다. 사용자 설정은 ~/.gemini/settings.json, 프로젝트 설정은 .gemini/settings.json이에요.

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

평평한 contextFileName이 아니라 이렇게 중첩 형태로 적어야 합니다. 기본 이름 목록에는 AGENTS.md가 없어서, 다른 도구와 같은 AGENTS.md를 쓰려면 이렇게 적어 줘야 해요. 도구별로 어떤 파일을 읽는지는 CLAUDE.md·AGENTS.md·GEMINI.md 비교에 정리했습니다.

@로 쪼개기

파일이 길어지면 본문에 @경로.md를 적어 다른 파일을 가져옵니다.

• 서로를 가져오는 순환은 자동으로 막힙니다.
• 중첩 깊이는 기본 5단계까지입니다.
• 상대 경로와 절대 경로를 모두 받습니다.
• 코드 블록과 인라인 코드 안의 @는 가져오기로 해석하지 않습니다.
• 허용된 폴더 안의 파일만 가져올 수 있습니다.

.geminiignore로 빼기

컨텍스트에서 제외할 경로는 .geminiignore에 적습니다. 빈 줄, # 주석, 글롭 패턴, 끝의 /(폴더만), 앞의 /(위치 고정), !(부정)까지 대체로 .gitignore 관례를 따라요. 바꾼 내용은 세션을 다시 시작해야 적용됩니다.

읽혔는지 확인하는 /memory

대화 화면에서 /memory 명령 네 개로 확인합니다.

• /memory list: 로드된 GEMINI.md 파일 경로 목록
• /memory show: 이어 붙여진 전체 내용
• /memory reload: 모든 위치에서 다시 읽어 모델에 반영
• /memory inbox: Auto Memory 후보 검토(실험 기능)

CLI 화면 아래쪽 푸터에도 로드된 컨텍스트 파일 개수가 표시되니까, 숫자가 예상과 다르면 /memory list부터 열어 보세요.

다시 읽는 명령은 문서마다 reload·refresh로 이름이 다르게 적혀 있습니다. 0.60.0 패키지의 명령 정의를 직접 열어 보니 정식 이름은 reload이고 refresh가 별칭으로 등록돼 있더라고요. 어느 쪽을 쳐도 됩니다.

/memory inbox는 Auto Memory 기능이 지난 세션에서 뽑아낸 기억 후보를 검토하는 화면입니다. Auto Memory는 실험 기능이라 experimental.autoMemory의 기본값 false로 꺼져 있고, 켜면 후보는 승인하거나 버리기 전까지 프로젝트 안의 수신함에 머뭅니다.

에이전트가 스스로 기억을 적을 때는 세 곳에 나눠 씁니다. 공유할 프로젝트 지시는 저장소의 GEMINI.md, 개인적인 프로젝트 메모는 프로젝트별 비공개 메모리 폴더, 프로젝트를 넘나드는 개인 선호는 ~/.gemini/GEMINI.md예요.

안 읽힐 때 먼저 볼 것

/memory show가 비어 있을 때

공개 이슈로 보고된 원인은 셋입니다. 이름이 기본값과 다르거나, 대소문자가 어긋났거나, 설정 키 형태가 다른 경우예요(아래 사례). 셋 다 위치가 아니라 이름·설정 쪽이었습니다.

그러니 파일을 옮기기 전에 /memory list로 로드된 경로부터 보세요. 목록이 비어 있으면 context.fileName이 중첩 형태로 적혀 있는지, 파일 이름 철자와 대소문자가 설정과 정확히 같은지 확인하면 됩니다.

상위 폴더에 둔 공통 규칙이 반영되지 않을 때

위쪽 탐색이 .git이 있는 폴더에서 멈추기 때문입니다. 서브모듈 안에서 실행하면 안쪽 .git에서 먼저 멈춰요. 공통 규칙을 저장소 안으로 옮기고 @경로.md로 가져오거나, context.includeDirectories로 그 폴더를 더한 뒤 context.loadMemoryFromIncludeDirectories를 켜세요.

파일을 고쳤는데 세션이 옛 내용을 따를 때

이어 붙인 내용은 이미 시스템 프롬프트에 들어가 있고, 새로 읽는 건 따로 명령해야 합니다. /memory reload를 실행하세요. .geminiignore를 고쳤다면 세션을 다시 시작해야 합니다.

다른 사람들이 겪은 문제

네 건 모두 파일은 제자리에 있는데 내용이 세션에 반영되지 않은 경우이고, 세 건은 보고자가 /memory show로 확인했습니다.

• 설정 키 형태: WuJunkai2004(2026-05-09, #26728, 닫힘)는 settings.json에 평평한 contextFileName으로 AGENTS.md를 적었을 때는 안 읽히고, 중첩된 context.fileName으로 바꾸자 읽혔다고 보고했습니다. 다만 그 뒤로 전역 GEMINI.md 내용이 /memory show에서 보이지 않았다고 덧붙였습니다. CLI 0.40.0.
• 기본 이름: chirag127(2026-07-01, #28227, 열림)은 AGENTS.md를 쓰던 저장소에서 그 파일이 경고 없이 안 붙고, /memory show로 봐야 알 수 있다고 보고했습니다. v0.49.0 기준 기본 이름은 GEMINI.md 하나이고, 0.60.0 문서도 같습니다.
• 대소문자: mishka-zz(2026-05-08, #26700, 계획 없음으로 종료)는 대소문자를 구분하는 APFS의 macOS에서 ~/.gemini/GEMINI.md가 /memory show에 안 나왔고, 소문자 gemini.md로 바꾼 뒤 /memory reload를 하니 로드됐다고 적었습니다. CLI 0.41.2.
• 서브모듈 경계: Kizuno18(2026-04-19, #25658, 닫힘)은 서브모듈 안에서 실행하면 안쪽 .git에서 탐색이 멈춰 부모 저장소의 컨텍스트 파일이 잡히지 않는다며 개선을 요청했고, 규칙을 각 서브모듈에 복사하거나 가져오기로 잇는 우회를 함께 적었습니다. Windows 11.

네 건을 나란히 놓고 보면, 파일을 어디에 뒀느냐보다 이름과 설정 키가 문제였던 경우가 더 많습니다.

마치며

GEMINI.md는 “어디에 두느냐”가 거의 전부인 파일처럼 보이지만, 공개된 사례를 모아 보면 안 읽히는 원인은 위치보다 이름·대소문자·context.fileName 형태 쪽이 더 많았습니다. 그래서 파일을 옮기기 전에 프로젝트 폴더에서 gemini를 열고 /memory list로 읽힌 파일 경로가 예상과 같은지부터 보세요. 그 한 번이 파일을 이리저리 옮기는 것보다 빠릅니다.

Antigravity CLI로 옮긴다면, 작업 폴더의 GEMINI.md와 AGENTS.md를 그대로 읽는 것까지는 직접 확인했습니다. 이 글의 .git 경계, context.* 설정 키, /memory 명령이 Antigravity CLI에서도 같은지는 옮긴 뒤에 따로 확인하세요.

설정 파일끼리 겹칠 때 어느 값이 이기는지는 Gemini CLI settings.json 네 파일의 우선순위에 이어서 정리했습니다.