서론
솔직히 말하자면, AI 도구를 사용하면서 매번 짜증나는 것은 프로젝트의 규약, 코드 스타일, 기술 스택을 반복해서 설명해야 한다는 점입니다. 마치 매일 기억력이 좋지 않은 동료에게 "내가 누구지?"라고 설명하는 것과 같아서, 시간 낭비일 뿐만 아니라 실수의 원인이 되기도 합니다.
그런 때 발견한 것이 Gemini CLI의 숨겨진 기능인 GEMINI.md 파일입니다. 언뜻 보기에는 일반 Markdown 파일처럼 보이지만, 사실 이것은 Gemini CLI의 "기억 시스템"입니다. 프로젝트 규칙을 이 파일에 작성해 두기만 하면 AI가 여러분의 선호도를 기억하고, 생성되는 코드, 문서, PR 설명문까지도 프로젝트 스타일에 맞게 됩니다.
작은 팁：API 키나 비밀번호와 같은 민감한 정보는 여기에 작성하지 마세요. 환경 변수나 시크릿 관리를 사용하는 것이 더 안전합니다.
이제 AI에게 프로젝트를 반복해서 설명할 필요 없이, 그 시간을 코드 작성이나 로직 설계에 집중할 수 있게 됩니다!
일、GEMINI.md란 무엇인가?
간단히 말하면, GEMINI.md는 AI를 위한 "프로젝트 설명서"입니다. 이 파일로 AI에게 전달할 수 있는 내용:
- 프로젝트의 코딩 규약과 모범 사례
- 코드 스타일 선호도
- 자주 사용하는 라이브러리와 프레임워크
- 프로젝트 배경과 비즈니스 로직
예를 들어, React + TypeScript 프로젝트에서 사용할 경우, 컴포넌트 명명 규칙, 상태 관리 방법, 테스트 커버리지 요구사항 등을 모두 작성해 두면 AI가 생성하는 코드는 거의 수정이 필요 없게 됩니다.
경험담: 저는 "필수" 규칙을 명확히 작성하고, "선호도"는 옵션으로 명시합니다. 그렇게 하면 AI가 코드를 생성할 때 혼란스러워하지 않습니다.
작동 원리
Gemini CLI는 시작 시 자동으로 GEMINI.md 파일을 검색하고, 그 내용을 컨텍스트(즉, AI의 "기억")로 로드합니다. 검색은 재귀적으로 이루어지며, 현재 디렉토리에서 프로젝트 루트 디렉토리까지 거슬러 올라가 발견된 모든 GEMINI.md 파일이 통합됩니다. 이때 현재 디렉토리에 가까운 설정일수록 우선순위가 높습니다.
팀 실전 예: 서브디렉토리의 우선순위가 높은 것은 매우 중요합니다. 특정 모듈에는 특별한 규칙이 필요하고, 그것이 프로젝트 전체 규약에 영향을 주지 않도록 할 수 있기 때문입니다.
이、계층화 설정 — AI에게 프로젝트를 더 깊이 이해시키기
3층 설정 시스템
Gemini CLI는 계층화된 GEMINI.md 설정을 지원하며, 우선순위가 낮은 것부터 높은 것까지 다음과 같이 분류됩니다:
- 글로벌 설정:
~/.gemini/GEMINI.md(모든 프로젝트에 적용되는 공통 규칙) - 프로젝트 설정: 현재 디렉토리에서 프로젝트 루트 디렉토리 사이에 있는
GEMINI.md파일 - 서브디렉토리 설정: 특정 컴포넌트나 모듈용 전용 지시사항(로컬 오버라이드)
실제 설정 예
다음은 제가 여러 프로젝트에서 자주 사용하는 3가지 계층의 예입니다:
- 글로벌 설정(
~/.gemini/GEMINI.md):
# 내 개발 환경 설정
## 공통 코딩 규약
- 모든 코드에 상세한 주석 포함
- 함수명은 카멜케이스 사용
- JavaScript보다 TypeScript 선호
- 오류 처리는 try-catch 블록 사용
## 선호하는 기술 스택
- 프론트엔드: React + TypeScript + Tailwind CSS
- 백엔드: Node.js + Express + MongoDB
- 테스트: Jest + React Testing Library경험담: 자주 변경되지 않는 "스타일/선호도"는 글로벌에 두면 각 프로젝트에서 반복해서 작성하는 수고를 덜 수 있습니다.
- 프로젝트 루트 디렉토리 설정(
./GEMINI.md):
# EC 사이트 프로젝트
## 프로젝트 개요
이것은 마이크로서비스 아키텍처 기반 EC 사이트로, 사용자 관리, 상품 관리, 주문 처리 등의 주요 기능을 포함합니다.
## 프로젝트 특정 규약
- API는 RESTful 설계를 따름
- 모든 데이터베이스 작업에는 Prisma ORM 사용
- 프론트엔드 컴포넌트는 반응형 디자인 지원
- 결제 관련 코드에는 추가 보안 검사 필요
## 디렉토리 구조
-`/src/components/` - 재사용 가능한 React 컴포넌트
-`/src/pages/` - 페이지 레벨 컴포넌트
-`/src/api/` - API 정의
-`/src/utils/` - 유틸리티 함수- 컴포넌트 디렉토리 설정(
./src/components/GEMINI.md):
# 컴포넌트 개발 규약
## 컴포넌트 설계 원칙
- 각 컴포넌트에는 해당하는 .stories.js 파일 필요
- 컴포넌트는 다크 모드 지원
- 모든 props에는 TypeScript 타입 정의 필요
- 컴포넌트에는 단위 테스트 포함
## 스타일 규약
- Tailwind CSS 클래스명 사용
- 인라인 스타일 피하기
- 반응형 디자인 우선경험담: 로컬 규칙(컴포넌트 디렉토리 등)의 우선순위가 가장 높으며, 공통 규칙의 "예외"를 커버하는 데 적합합니다.
삼、모듈화 관리 — 설정을 더 우아하게
프로젝트가 복잡해지면 @file.md 구문을 사용하여 다른 Markdown 파일을 가져오고 설정을 모듈화할 수 있습니다. 이를 통해 GEMINI.md가 더 관리하기 쉬워지고 팀 협업도 용이해집니다.
@import 구문 사용 예
- 메인 설정 파일(
GEMINI.md):
# 풀스택 프로젝트
## 기본 설정
@./docs/coding-standards.md
@./docs/git-workflow.md
## 기술 스택 특정 설정
@./frontend/react-guidelines.md
@./backend/api-guidelines.md
@./database/schema-guidelines.md- 프론트엔드 규약(
./frontend/react-guidelines.md):
# React 개발 규약
## 컴포넌트 구조
- 함수 컴포넌트와 Hooks 사용
- 커스텀 Hook은 "use"로 시작
- 컴포넌트 파일명은 파스칼 케이스
## 상태 관리
- 간단한 상태에는 useState
- 복잡한 상태에는 useReducer
- 글로벌 상태에는 Zustand경험담: 공통 규약은
docs/에, 모듈/서비스 특정 항목은 해당 서브디렉토리에 둡니다. CI에서도 필요한 모듈 파일만 동기화할 수 있습니다.
사、실전 예 — 제로에서 완벽한 협업까지
예1: React + TypeScript 프로젝트 설정
프로젝트를 생성하고 GEMINI.md를 초기화합니다:
mkdir my-react-app
cd my-react-app
# 메인 설정 파일 생성
vim GEMINI.md완전한 프로젝트 설정:
# React TypeScript 프로젝트
## 프로젝트 정보
- 프로젝트명: 모던 Todo 앱
- 기술 스택: React 18 + TypeScript + Vite + Tailwind CSS
- 상태 관리: Zustand
- 라우팅: React Router v6
## 개발 규약
### 코드 스타일
- 들여쓰기는 2 스페이스
- 문자열은 단일 따옴표 선호
- 컴포넌트의 props는 구조 분해 할당 사용
- any 타입 사용 피하기
### 컴포넌트 규약
- 컴포넌트 파일은 .tsx 확장자 사용
- 컴포넌트 이름은 파스칼 케이스
- 컴포넌트는 기본 내보내기로 출력
- 각 컴포넌트에는 해당하는 타입 정의 필요
### 스타일 규약
- Tailwind CSS로 스타일 설계
- 반응형 디자인 우선(모바일 퍼스트)
- 다크 모드 지원
- 테마 색상에는 CSS 변수 사용
### 테스트 요구사항
- 각 컴포넌트에는 단위 테스트 필요
- React Testing Library 사용
- 테스트 커버리지는 80% 이상
## 프로젝트 특정 지시사항
- 생성되는 코드에는 상세한 JSDoc 주석 포함
- API 호출에는 오류 처리 포함
- 폼 유효성 검사에는 react-hook-form + zod 사용
- 모든 비동기 작업에는 React Query 사용경험담: 구체적일수록 좋습니다. 예를 들어, JSDoc 형식이나 매개변수 명명 규칙을 명확히 하면 AI가 더 일관된 주석을 생성합니다.
예2: 풀스택 프로젝트의 계층 설정
복잡한 풀스택 프로젝트에서는 루트 디렉토리를 "계약"으로 하고 서브디렉토리에서 로컬 오버라이드를 수행합니다:
- 프로젝트 루트 디렉토리(
./GEMINI.md):
# 풀스택 EC 사이트
## 프로젝트 아키텍처
- 프론트엔드: Next.js 14 + TypeScript
- 백엔드: Node.js + Express + Prisma
- 데이터베이스: PostgreSQL
- 배포: Docker + Kubernetes
## 공통 규약
@./docs/general-guidelines.md
@./docs/security-guidelines.md
@./docs/performance-guidelines.md
## 환경 설정
- 개발 환경: 로컬 PostgreSQL
- 테스트 환경: 인메모리 데이터베이스
- 프로덕션 환경: 클라우드 데이터베이스- 프론트엔드 설정(
./frontend/GEMINI.md):
# 프론트엔드 개발 규약
## Next.js 특정 규약
- App Router 사용(Pages Router 아님)
- 서버 컴포넌트 우선, 클라이언트 컴포넌트는 필요에 따라
- 이미지에는 next/image 컴포넌트 사용
- 폰트는 next/font로 최적화
## 상태 관리
- 서버 상태: TanStack Query
- 클라이언트 상태: Zustand
- 폼 상태: React Hook Form- 백엔드 설정(
./backend/GEMINI.md):
# 백엔드 개발 규약
## API 설계
- RESTful 원칙을 엄격히 따름
- OpenAPI 3.0 사양 사용
- 모든 API에는 입력 검증 필요
- 오류 응답은 통일된 형식 사용
## 데이터베이스 작업
- Prisma ORM 사용
- 모든 쿼리에는 오류 처리 포함
- 민감한 작업은 로그 기록
- 복잡한 작업에는 트랜잭션 사용경험담: API 관리에서는 Apidog를 함께 사용하여 API 문서와 테스트를 유지하는 것이 좋습니다. 백엔드
GEMINI.md에 정의된 API는 Apidog에서 직접 API 문서와 테스트 케이스를 생성할 수 있어 프론트엔드와 백엔드의 협업 효율이 크게 향상됩니다. 새 팀원도 문서만 보면 바로 작업을 시작할 수 있어 API 세부 사항에 대해 반복적으로 질문할 필요가 없습니다.
오、고급 기법과 모범 사례
동적 컨텍스트 관리
/memory show 명령을 사용하여 현재 로드된 모든 컨텍스트를 확인할 수 있습니다:
gemini
> /memory show이를 통해 로드된 모든 GEMINI.md 파일의 내용이 표시되어 설정이 올바른지 확인할 수 있습니다.
경험담:
GEMINI.md를 변경한 후에는 먼저/memory show를 실행하여 새 컨텍스트가 로드되었는지 확인합니다. 로드되지 않은 경우 CLI 캐시를 확인하거나 세션을 재시작합니다.
조건부 설정
개발 단계에 따라 다른 설정 파일을 만들 수 있습니다:
# 개발 단계 설정
## 현재 개발 포커스
- 사용자 인증 모듈 개발 중
- 기능 구현 우선, 성능 최적화는 나중에
- 디버깅에는 console.log 사용 가능
## 임시 규칙
- 임시로 any 타입 사용 허용(개발 완료 후 수정)
- API는 모의 데이터 반환 가능경험담: "임시 규칙"에는 기한이나 이슈 번호를 추가하면 정리를 잊지 않습니다.
팀 협업 설정
팀용 표준화된 설정 템플릿:
# 팀 개발 규약 v2.1
## 코드 리뷰 요구사항
- 모든 PR은 최소 2명의 리뷰 필요
- 새 기능에는 테스트 케이스 포함
- 파괴적 변경에는 문서 업데이트 필요
## 커밋 규약
- Conventional Commits 형식 사용
- 커밋 메시지에는 이슈 번호 포함
- 각 커밋은 하나의 논리적 변경만 포함
## 브랜치 전략
- main 브랜치: 프로덕션 환경 코드
- develop 브랜치: 개발 환경 코드
- feature/*: 기능 개발 브랜치
- hotfix/*: 긴급 수정 브랜치실전 조언:
GEMINI.md를 팀 합의의 일부로 취급하고 저장소에 저장하여 PR 리뷰를 강제합니다. 이를 통해 AI가 PR 설명, 커밋 메시지, 코드를 생성할 때 팀 워크플로우를 참조할 수 있습니다.
육、자주 발생하는 문제와 해결책
문제 일: 설정이 반영되지 않음
증상: AI가 생성한 코드가 GEMINI.md의 규약을 따르지 않음
해결책:
- 파일 경로와 이름이 올바른지 확인
/memory show를 사용하여 설정이 로드되었는지 확인- 설정 설명이 충분히 명확하고 구체적인지 확인
추가 확인: 파일이 UTF-8 형식인지, BOM이 없는지, 권한이 올바른지, 파일 끝에 숨겨진 문자가 없는지 확인합니다.
문제 이: 설정 충돌
증상: 다른 계층의 설정이 모순됨
해결책:
- 우선순위 이해: 서브디렉토리 > 프로젝트 > 글로벌
- 명시적 오버라이드 문 사용
- 오래된 설정 정기적 정리
조언: 각 서브디렉토리의
GEMINI.md서두에 "오버라이드 설명"을 작성하여 이 파일이 상위 규칙을 오버라이드하는 이유를 설명합니다.
문제 삼: 설정이 너무 복잡함
증상: GEMINI.md 파일이 관리하기 어려워짐
해결책:
@import구문으로 모듈화- 정기적으로 리팩토링하여 설정 간소화
- 정말 필요한 규칙만 남기기
저는 보통 분기마다 "설정 리뷰"를 실시하여 오래되거나 사용되지 않는 규칙을 제거하고 유지보수 부담을 줄입니다.
칠、응용 시나리오
시나리오 일: 다국어 프로젝트 설정
# 다국어 풀스택 프로젝트
## 언어별 규약
### Python 백엔드
- PEP 8 규약 준수
- type hints 사용
- 문서 문자열은 Google 형식
### Go 마이크로서비스
- gofmt로 포맷팅
- 오류 처리 무시하지 않기
- API 설계는 Go 관례 따르기
### TypeScript 프론트엔드
- 엄격 모드 활성화
- any 타입 금지
- ESLint + Prettier 사용실전 조언: 각 언어의 CI/CD 파이프라인에 lint/format 프로세스를 추가하면 AI가 이러한 검사를 준수하는 코드를 생성하는 경향이 강해집니다.
시나리오 이: AI를 통한 리팩토링 지원
# 코드 리팩토링 프로젝트
## 리팩토링 목표
- 클래스 컴포넌트를 함수 컴포넌트로 마이그레이션
- jQuery 의존성 제거하고 네이티브 JavaScript 사용
- 성능 최적화하고 재렌더링 줄이기
## 리팩토링 원칙
- 기능 변경하지 않기
- 단계적으로 마이그레이션하고 대규모 재작성 피하기
- 리팩토링 후 완전한 테스트 실행
- 기존 API 유지실전 조언: 리팩토링 범위(파일 목록, 단위 테스트 요구사항)를 명확히 하고 AI에게 롤백 가능한 패치 형식의 변경을 출력하도록 합니다.
시나리오 삼: 문서 생성 설정
# 문서 생성 규약
## API 문서 요구사항
- OpenAPI 3.0 형식 사용
- 요청/응답 예제 포함
- 오류 코드 설명 완전히
- 인증 정보 포함
## 코드 문서 요구사항
- 모든 공개 메서드에 JSDoc 첨부
- 복잡한 알고리즘에는 상세한 주석
- 사용 예제 포함
- 매개변수 타입과 반환값 설명실전 조언:
GEMINI.md에 실제 예제(요청/응답)를 1, 2개 첨부하면 AI가 문서를 생성할 때 이러한 샘플을 재사용하여 품질이 향상됩니다.
결론
GEMINI.md 파일은 단순한 설정 파일이 아니라 여러분과 AI 어시스턴트 사이의 "계약"입니다. 세심하게 설계된 설정을 통해 다음이 가능해집니다:
작은 팁: 저는 Apidog를 사용하여 API 문서와 테스트를 관리하는 경우가 많습니다. 이를 통해
GEMINI.md규칙을 API 생성 및 검증 프로세스에 직접 매핑할 수 있어 개발 효율성과 협업 경험이 크게 향상됩니다.
- 개발 효율성 향상: 반복적인 설명이 필요 없어지고 AI가 직접 여러분의 요구사항을 이해
- 코드 품질 보장: 통일된 규약으로 팀 협업이 원활하게
- 학습 비용 감소: 새로운 팀원이 설정을 통해 프로젝트 규약을 빠르게 이해
- 개인화: AI 어시스턴트가 여러분의 개발 습관에 완전히 적응
좋은 GEMINI.md 설정은 다음과 같아야 합니다:
- 명확하고 구체적: 모호한 설명 피하기
- 단계적: 간단하게 시작하여 점진적으로 개선
- 정기적 업데이트: 프로젝트 발전에 맞춰 설정 조정
- 팀의 합의: 모든 구성원이 이해하고 따름
지금 바로 여러분의 프로젝트에 GEMINI.md 파일을 만들어보세요! Gemini CLI를 여러분을 진정으로 이해하는 지능적인 프로그래밍 파트너로 만들어보세요!
