gemini.md 작성법 — 로드 순서와 파일명 바꾸기
GEMINI.md는 매번 같은 지시를 프롬프트에 다시 쓰지 않으려고 만드는 컨텍스트 파일입니다. 딱 세 가지만 알면 됩니다. ① 파일은 홈의 ~/.gemini/GEMINI.md → 작업 폴더와 그 상위 폴더 → 도구가 파일을 만질 때 그 폴더 순서로 읽혀 전부 이어 붙여 모델에 갑니다. ② 파일명은 기본이 GEMINI.md 하나뿐이라, AGENTS.md를 같이 읽히려면 설정에 이름을 직접 넣어야 합니다. ③ 지금 뭐가 읽히는지는 /memory list로 확인합니다. 아래는 Gemini CLI 0.56.0 기준으로 하나씩 확인한 내용입니다.
1. GEMINI.md는 어디에 두나 — 읽히는 순서
공식 문서는 "여러 위치에서 컨텍스트 파일을 불러와 찾은 파일 내용을 전부 이어 붙여 매 프롬프트와 함께 모델에 보낸다"고 적고 있습니다. 하나만 골라 읽는 게 아니라 합쳐진다는 게 핵심입니다.
| 순서 | 위치 | 언제 쓰나 |
|---|---|---|
| 1. 전역 | ~/.gemini/GEMINI.md |
모든 프로젝트에 걸리는 기본 지시(말투, 답변 언어 등) |
| 2. 워크스페이스 | 작업 폴더와 그 상위 폴더들의 GEMINI.md |
지금 프로젝트의 규칙(빌드 명령, 코딩 스타일) |
| 3. JIT(필요할 때) | 도구가 건드린 파일·폴더와 그 조상 폴더 | 특정 모듈에만 해당하는 좁은 지시 |
3번이 의외로 유용합니다. 모노레포처럼 폴더마다 규칙이 다른 저장소라면, 루트에 전부 몰아 쓰는 대신 packages/api/GEMINI.md에 그 모듈 규칙만 두면 됩니다. 그 폴더의 파일을 실제로 건드릴 때만 읽히니 평소 컨텍스트가 붓지 않습니다.
2. 처음 만들 때는 /init
빈 화면부터 시작할 필요는 없습니다. 프로젝트 폴더에서 CLI를 켜고 /init을 치면, 설명 그대로 "프로젝트를 분석해 그 프로젝트에 맞춘 GEMINI.md를 만들어 줍니다".
/initGEMINI.md가 있는 폴더에서 /init을 치면 덮어쓰지 않고 "A GEMINI.md file already exists in this directory. No changes were made."라고 알려 주고 끝납니다. 기존 파일이 날아갈 걱정은 없습니다.
3. 무엇을 쓰나 — 실제로 지켜지는 문장
공식 예시는 타입스크립트 프로젝트를 이렇게 적습니다.
# Project: My TypeScript Library
## General Instructions
- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
## Coding Style
- Use 2 spaces for indentation.
- Prefix interface names with `I` (for example, `IUserService`).
- Always use strict equality (`===` and `!==`).형식은 그냥 마크다운입니다. 특별한 문법이 없으니, 잘 쓰는 요령은 하나로 모입니다 — 검사할 수 있는 문장으로 적는 것입니다. "코드를 깔끔하게 짜라"는 지킨 건지 아닌지 알 수가 없지만, "들여쓰기는 공백 2칸", "테스트는 npm test로 돌린다"는 결과만 봐도 판별됩니다. 같은 원칙이 다른 도구의 지시 파일에도 그대로 적용돼서, claude.md 작성법이나 agents.md 작성법에서 정리한 요령을 그대로 옮겨 써도 됩니다.
4. 파일이 길어지면 @로 쪼갠다
한 파일에 다 몰아넣지 말고 @경로로 다른 파일을 끌어올 수 있습니다. 상대 경로(@./, @../)와 절대 경로(@/) 둘 다 됩니다.
# Main GEMINI.md file
This is the main content.
@./components/instructions.md
More content here.
@../shared/style-guide.md불러온 파일 안에서 또 불러오는 중첩도 됩니다. 대신 안전장치가 걸려 있습니다 — 서로를 부르는 순환 임포트는 자동으로 막히고, 무한 재귀를 막으려고 임포트 깊이가 기본 5단계로 제한됩니다. 코드 블록이나 인라인 코드 안에 있는 @는 임포트로 읽지 않으니, 문서에 이메일 주소나 데코레이터를 적어 두었다고 파일을 찾아 헤매지 않습니다.
5. AGENTS.md도 같이 읽히게 하려면 — context.fileName
여기서 많이 헷갈립니다. Gemini CLI가 기본으로 읽는 파일명은 GEMINI.md 하나뿐입니다. 0.56.0 설치본을 열어 봐도 기본 파일명 상수는 "GEMINI.md" 하나이고, AGENTS.md는 설정 예시 문자열에만 등장합니다. 즉 저장소에 AGENTS.md만 두고 "왜 안 읽지?"라고 하는 상황이 그대로 생깁니다.
같이 읽히게 하려면 settings.json에 이름을 직접 적어 줍니다. 문자열 하나도 되고, 배열로 여러 개도 됩니다.
{
"context": {
"fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
}
}context.fileName입니다(옛 글에 보이는 최상위 contextFileName이 아니라 context 아래로 들어갑니다). 0.56.0 설정 스키마의 설명도 "메모리에 불러올 컨텍스트 파일 이름 — 문자열 하나 또는 문자열 배열"입니다.
6. 지금 뭐가 읽혔는지 확인하기 — /memory
가장 자주 쓸 명령입니다. 0.56.0 기준 /memory의 하위 명령은 네 개입니다.
| 명령 | 하는 일 |
|---|---|
/memory show |
이어 붙여진 컨텍스트 전문을 그대로 보여 준다 |
/memory list |
지금 쓰이는 GEMINI.md 파일들의 경로를 나열한다 |
/memory reload |
파일을 고친 뒤 다시 읽어 들인다 |
/memory inbox |
지난 세션에서 뽑힌 스킬을 검토해 전역·프로젝트로 옮긴다 |
파일을 고쳤는데 반응이 그대로면 /memory reload부터 치고, 그래도 아니면 /memory list로 내가 고친 그 파일이 목록에 있는지 봅니다. 아무것도 안 잡히면 "No GEMINI.md files in use."라고 뜹니다.
/memory add는 0.56.0에는 없습니다. 하위 명령은 위 네 개뿐입니다.
7. 아무리 고쳐도 안 먹을 때 — 폴더 신뢰 설정
경로도 맞고 /memory reload도 했는데 아예 안 읽히면, 그 폴더가 신뢰하지 않는 폴더로 잡혔을 가능성이 큽니다. 이때 CLI가 내놓는 안내가 명확합니다 — "이 폴더는 신뢰되지 않아 프로젝트 설정, 훅, MCP, 그리고 GEMINI.md 파일이 적용되지 않는다"는 문구가 뜹니다.
남이 만든 저장소를 클론해 처음 열었을 때 잘 걸립니다. 같은 이유로 MCP 서버도 함께 무시되니, gemini cli mcp 설정이 갑자기 안 붙는 것처럼 보인다면 이 안내 문구가 떴는지부터 확인하는 게 빠릅니다.
8. 안티그래비티 CLI로 넘어가면 이 파일은 어떻게 되나
개인 사용자 기준으로 Gemini CLI가 정리 수순에 들어가면서(자세한 날짜와 대상은 gemini cli 서비스 종료 글에 정리해 두었습니다) "그럼 GEMINI.md는 버리는 건가" 하는 질문이 따라옵니다. 답은 아니오입니다. 공식 마이그레이션 문서가 "두 CLI는 워크스페이스 컨텍스트 규칙이 동일하며, 기존 규칙 문서를 고칠 필요가 없다"고 못박고 있습니다.
| 항목 | Gemini CLI 0.56.0 | Antigravity CLI |
|---|---|---|
| 작업 폴더 컨텍스트 | GEMINI.md (기본값) |
GEMINI.md와 AGENTS.md 둘 다 |
| 전역 컨텍스트 | ~/.gemini/GEMINI.md |
~/.gemini/GEMINI.md (그대로) |
| 워크스페이스 규칙 폴더 | — | .agents/rules (옛 .agent/rules도 계속 인식) |
즉 전역 파일 경로는 손댈 필요가 없고, AGENTS.md는 오히려 설정 없이 그냥 읽힙니다. 다만 안티그래비티 쪽 규칙 파일에는 파일당 12,000자 제한이 걸려 있으니, 양쪽에서 같이 쓸 문서라면 처음부터 @ 임포트로 쪼개 두는 편이 안전합니다.
자주 묻는 질문 (FAQ)
Q. 전역 파일과 프로젝트 파일에 서로 반대되는 지시를 쓰면 어느 쪽이 이기나요?
공식 문서가 말하는 건 "정해진 순서로 불러와 내용을 이어 붙인다"는 것까지입니다. 어느 쪽이 이긴다는 우선순위 규칙은 문서에 없습니다. 그러니 충돌 자체를 만들지 않는 게 맞습니다 — 전역에는 어느 프로젝트에서나 통하는 것(답변 언어, 말투)만 두고, 프로젝트 규칙은 프로젝트 파일에 둡니다.
Q. 파일을 고쳤는데 반영이 안 됩니다.
/memory reload → /memory list 순으로 확인합니다. 목록에 그 경로가 없으면 위치가 틀렸거나(작업 폴더나 그 상위가 아님), 파일명이 GEMINI.md가 아니거나, 7번의 신뢰하지 않는 폴더 상태입니다.
Q. 파일 하나에 다 쓰는 게 나은가요, 나눠 쓰는 게 나은가요?
전부 읽히는 만큼 프롬프트마다 따라붙는 분량이니, 길이는 그 자체로 비용입니다. 모든 프로젝트에 공통인 것만 전역에 두고, 모듈에만 해당하는 규칙은 그 폴더의 파일로 내려 두는 편이 낫습니다. 그래야 그 폴더를 건드릴 때만 읽힙니다(1번의 3단계).
마무리
정리하면 이렇습니다. 위치는 전역 → 작업 폴더·상위 → 필요할 때 그 폴더 순으로 합쳐서 읽히고, 시작은 /init, 확인은 /memory list, 파일명을 바꾸거나 AGENTS.md를 더하려면 context.fileName입니다. 안 먹는다 싶을 때 열에 아홉은 위치·파일명·폴더 신뢰 셋 중 하나입니다.
CLI는 버전이 빨리 오르니, 하위 명령이나 설정 키가 이 글과 다르면 본인 환경의 버전을 gemini --version으로 확인하고 공식 문서를 한 번 열어 보세요.
📚 참고 출처 (2026년 9월 7일 확인 · 기준 Gemini CLI 0.56.0)
· Gemini CLI 공식 문서 — Provide context with GEMINI.md files
· Gemini CLI 공식 문서 — Memory Import Processor
· Antigravity CLI 공식 문서 — Migrating from Gemini CLI
· Antigravity 공식 문서 — Rules
COMMENTS