[AI 터미널 도구 16~17일차] Gemini CLI 고급 기능

Posted Mar 24, 2026 Updated Mar 28, 2026

By rkgh17

20 min read

도서명 : AI 자율학습 클로드 코드·코덱스 CLI·제미나이 CLI 완전 활용법

이 포스팅은 길벗 출판사의 코딩 자율학습단 20기 활동의 일환으로, 개인 공부 정리용 포스팅이다.

11장 - Gemini CLI 고급 기능 활용

11.1 - MCP 서버 연결

MCP 설정 파일의 구조와 위치 이해

MCP 설정은 전역 환경과 프로젝트 전용 환경 두 가지로 구분되며, 각각 독립적으로 작동

전역 설정
- Windows : C:\Users\사용자이름\.gemini\settings.json
- macOS/Linux : ~/.gemini/settings.json
- 이곳에 등록한 MCP 서버는 모든 프로젝트에서 자동으로 활성화되므로 다음과 같은 경우에 적합
  - 여러 프로젝트에서 공통으로 사용하는 MCP서버
  - Context7처럼 범용 개발 도구
  - 프로젝트마다 매번 반복 구성하기 싫은 환경
프로젝트 설정
- 위치 : 프로젝트폴더/.gemini/settings.json
- 다음과 같은 경우에 사용하면 적합
  - 특정 프로젝트 전용 MCP 서버
  - 다른 프로제트에는 불필요한 MCP가 로드되는 것을 피하고 싶을 때
  - 팀 단위로 MCP 구성을 Git으로 공유해야 할 때

MCP 서버 연결 방법

CLI 명령어로 MCP 서버 추가하기
기본 동작 : 프로젝트 범위 등록 gemini mcp add context7 npx @context7/cli mcp
전역 등록 : 모든 프로젝트에서 사용 gemini mcp add -s user <서버명> <실행_명령>

settings.json 직접 편집하기

command : MCP 서버를 실행하는 명령 또는 바이너리
args : 실행에 필요한 인자를 배열 형태로 지정

env : 인증 토큰 등 환경 변수 값 재정의

  
{
 "mcpServers" : {
 "서버명" : {
     "command" : "실행_명령",
     "args" : ["인자1", "인자2"],
     "env" : {
         "환경변수" : "값"
     }
 }
 }
}

MCP 서버 관리

MCP 서버 제거
1. 전역 또는 프로젝트 설정 파일을 연다
2. mcpServers에서 제거하려는 MCP 서버 블록을 삭제
3. JSON 문법 오류 확인
4. 터미널에서 gemini 명령으로 새 세션을 시작하면 변경 사항이 반영됨
필요한 MCP 서버만 선택적으로 활성화하기
1. 명령줄 옵션으로 MCP 서버 선택 로드 (일시 조정)
  - settings.json을 변경하지 않고, 지금 실행하는 세션에서만 특정 MCP 서버를 활성화하는 방식
  - 테스트 환경이나 단발성 작업에서 유용함
  - gemini --allowed-mcp-server-names playwright context7
2. settings.json 에서 MCP 서버 허용 목록 설정(영구 설정)
  - 특정 프로젝트에서 “이 MCP 서버만 사용한다”는 기준을 명확히 설정할 수 있다.
  - "mcp" : { "allowed" : ["playwright", "context7"] }

11.2 - 보안과 권한 관리

Gemini CLI의 보안 계층

승인 설정
- AI가 파일 수정(write_file, edit_file), 외부 명령 실행(bash) 등 중요한 작업을 수행하기 전에 사용자 승인을 요구
신뢰 폴더
- 폴더별 신뢰 여부를 지정해 신뢰하지 않는 폴더에서는 안전 모드를 적용
샌드박스
- 파일 시스템 접근을 프로젝트 폴더로 제한해 시스템 전체를 보호하는 격리 기능

신뢰 폴더

Gemini CLI에서 특정 프로젝트 폴더를 안전한 작업 환경으로 판단할지 여부를 결정하는 보안 기능. 다음과 같은 제한이 적용됨

신뢰하지 않는 폴더의 .gemini/settings.json 파일 무시
환경변수(.env) 자동 로딩 차단
확장 기능 설치 및 사용 제한
자동 승인(auto_edit 등) 비활성화
프로젝트 컨텍스트 자동 분석 기능 일부 제한

반대로 신뢰 폴더에서는 프로젝트 설정과 확장 기능이 정상적으로 동작. 보통 다음과 같은 상황에서 특히 유용하다.

Github에서 내려받은 외부 저장소를 분석할 때
인터넷에서 받은 예제 코드, 실습용 저장소를 열 때
보안이 확실하지 않은 외부 프로젝트를 검토할 때
폐쇄형 내부 프로젝트와 외부 코드가 섞여 있을 때

신뢰 폴더 설정

신뢰 폴더 기능 활성화
- ~/.gemini/settings.json에 다음 설정 추가
- "forderTrust":{"enabled":true}
처음 방문하는 폴더에서 Gemini CLI 실행
세션 중 신뢰 상태 변경
- 실행 중인 세션에서도 /permissions 명령으로 신뢰 여부를 다시 지정할 수 있다.
- /permissions trust .
신뢰 폴더 목록 확인 및 관리
- ~/.gemini/trustedFolders.json

샌드박스와 보안 설정 가이드

빠르게 샌드박스 모드 활성화
- 명령줄에서 즉시 활성화
  - gemini -s
- settings.json에서 기본값 지정
  - "sandbox": true
상황별 보안 설정 가이드
- 위험도가 높은 코드를 다룰 때 : 신뢰 안 함 + 샌드박스 활성화
- 빠른 테스트나 개발 : YOLO 모드
- 프로덕션 작업 : 자동 승인 금지, 신뢰 폴더만 사용
- 외부 저장소 분석 : 신뢰 안함 + 샌드박스 활성화
보안 체크리스트
- 기본 원칙
  - 기본 승인 모드로 시작하고, YOLO 모드는 Ctrl + Y로 일시적으로만 사용
  - 신뢰하지 않은 코드를 사용할 경우 샌드박스 + 신뢰 안 함 + 수동 승인 조합으로 실행
  - 중요한 파일을 작업하기 전에는 Git 커밋 또는 백업 남기기
- 정기 점검 항목
  - ~/.gemini/trustedFolders.json의 신뢰 목록 검토 > 실수로 외부 폴더가 신뢰 상태로 등록되지 않았는지 확인
  - 인터넷에서 가져온 외부 코드나 프롬프트는 실행하기 전 반드시 내용 검토
  - 프로덕션이나 회사 프로젝트는 외부 폴더와 분리해 관리
  - 환경 변수(.env) 사용, 신뢰하지 않은 폴더에서는 자동 로딩이 차단됨을 인지

11.3 - 고급 설정 : settings.json 활용

settings.json 구조 이해

settings.json은 단순한 환경 설정 파일이 아니라 모델 선택 -> UI 구성 -> 보안 정책 -> MCP서버 -> 에디터 환경까지 Gemini CLI의 모든 행동 규칙을 정의하는 핵심 구성 요소이다.

settings.json의 주요 구조
- model : 기본으로 사용할 Gemini 모델
- ui : 테마, 줄 번호 표시 등 터미널 UI
- security : 샌드박스, 신뢰 폴더 등 보안 관련 정책
- mcp/mcpServers : MCP서버 허용 정책 및 서버 실행 방식
- editor : 포매팅, 라인 래핑 등 에디터 옵션
settings.json을 다룰 때 기본 원칙
- 전역 설정에는 개인 취향, 기본 모델, 테마, 에디터 옵션을 둔다.
- 프로젝트 설정에는 프로젝트만의 규칙을 둔다.
- 테스트나 임시 변경은 명령줄 옵션으로 처리한다.

settings.json 편집

편집 방식은 크게 두가지로 나뉜다.

전역 설정을 편집해 전체 기본값을 바꾸는 방식
- 전역 설정 파일 : ~/gemini/settings.json
- 사용자의 모든 Gemini CLI 세션에 공통으로 적용되는 기본 환경
- 편집 절차
  1. Cursor 또는 사용 중인 에디터를 실행해 사용자 홈 폴더를 연다.
  2. ~/gemini/settings.json 파일을 찾는다. 파일이 없다면 새로 생성한다.
  3. 모델, UI, 보안 정책 등 필요한 설정을 추가하거나 수정한다.
    - "model":{"name" : "gemini-3-pro"}
  4. 파일을 저장한 후 Gemini CLI를 다시 실행하면 변경사항이 적용
- 모든 프로젝트에 동일하게 적용되는 기본 규칙을 정의하는 영역이므로 단순하지만 구조적으로 중요한 설정에 집중하는 것이 좋다.
프로젝트 설정을 구성해 특정 프로젝트만 다른 규칙을 적용하는 방식
- 프로젝트마다 요구 사항이 다른 경우, 프로젝트 루트에 위치한 .gemini/settings.json을 사용하면 해당 프로젝트에만 적용되는 독립적인 환경을 만들 수 있다.
- 편집 절차
  1. Cursor에서 해당 프로젝트 폴더를 연다
  2. 프로젝트 루트에 .gemini폴더가 없다면 새로 생성한다
  3. .gemini/settings.json파일을 만들고 필요한 설정을 입력한다. 예를 들어, Playwright MCP만 허용한다고 지정하고 싶다면 다음과 같이 작성.
    - "mcp":{"allowed":["playwright"]}
  4. 파일을 저장하고 프로젝트 폴더에서 Gemini CLI를 실행.

주요 설정 카테고리 다루기

settings.json은 기능별로 카테고리가 나뉘어 있으며, 각 카테고리는 역할이 명확히 구분되어 있다. Gemini CLI는 지속적으로 업데이트하므로 세부 옵션은 공식 문서를 함께 참고하는 것을 권장한다.

모델 설정
- 모델 설정은 Gemini CLI가 어떤 모델을 사용할지, 세션을 어떻게 관리할지, 기본 답변 스타일을 어떻게 가져갈지 정의하는 영역이다. 실무에서 가장 자주 수정하는 카테고리
- 기본 모델 선택
  - "model":{"name":"gemini-3-flash"}
- 대화 히스토리 길이 제한
  - 대화가 길어질수록 히스토리를 모두 보관하는 것은 비용과 속도 측면에서 비효율적일 수 있음.
  - "model":{"maxSessionTurns":20}
    - -1(기본값) : 히스토리를 무제한으로 저장
    - 10~20 : 자동화 스크립트나 반복 작업용 세션에서 추천
- 컨텍스트 압축 기준
  - 대화가 길어지면 모델의 컨텍스트 한도에 가까워지기 전에 이전 내용을 요약해 압축할 수 있다.
    - "model":{"chatCompressions":{"contextPercentageThreshold":0.7}}
    - 0.7(기본) : 컨텍스트 사용량이 70%를 넘으면 자동으로 압축 시작
    - 0.8~0.9 : 대규모 파일 작업이 잦다면 0.8~0.9로 높이는 것도 방법
- 시스템 프롬프트
  - AI의 기본 성격을 정의하는 문장. 대화가 시작될 때 항상 먼저 적용되어 톤, 역할, 스타일에 영향을 준다.
  - "model": {"systemPrompt" : "You ar an expert Python developer.~~~"}
UI 커스터마이징
- 테마
  - "ui" : {"theme" : "Shades Of Purple"}
- 배너나 팁 표시 제어
  - hideBanner : 시작 시 환영 배너 숨김
  - hideTips : 작업 중 하단에 표시되는 팁 문구 숨김
  - showCitations : 응답에 참고 출처를 표시할지 여부
도구 설정
- 안전한 도구 자동 허용
  - "tools" : {"allowed" : ["read_file", "list_directory"]}
- 위험한 도구 차단
  - "tools" : {"exclude" : ["execute_command"]}
컨텍스트 설정
- 컨텍스트 파일 이름 지정
  - "context" : {"fileName" : ["GEMINI.md", "PROJECT_CONTEXT.md"]}
- 항상 인식할 디렉터리 지정
  - 소스코드 : src/
  - 문서 : docs/
  - 설정 : config/
  - 스키마, API : schema, api 등
- 디렉터리 내용 자동 로드
  - "context" : {"includeDirectories" : ["src"], "loadFromIncludeDirectories" : true}

11.4 - Gemini CLI 확장 기능 활용

Gemini CLI Companion : IDE 통합(vsCode, Cursor)

Gemini CLI Companion : 터미널에서 사용하던 Gemini CLI 기능을 IDE 환경에서도 그대로 활용할 수 있으며, 열린 파일이나 선택한 코드, Diff 기반 적용 등 IDE 워크플로와 AI 협업이 자연스럽게 연결된다.
터미널에서 매번 파일을 @로 지정하거나 경로를 설명하던 과정을 IDE에서 그냥 파일을 열어두는 것만으로 대체할 수 잇어 AI 기반 개발 흐름을 크게 단축시키는 도구

설치
- Extensions 검색창에 Gemini CLI Companion 검색
- 제공자가 Google인 공식 확장을 선택해 설치
- 재시작
- 연결상태 확인 : /ide status
- 연결 해제 : /ide disable
IDE 컨텍스트 자동 전달 기능
- Open Editor File Context - 열린 파일 자동감지
  - 최근 열어둔 최대 10개의 파일 경로를 자동으로 전달함.
    - > 이 컴포넌트를 리팩토링해줘
- Selection Context - 선택한 코드 자동 전달
  - IDE에서 선택한 텍스트(최대 약 16KB)를 그대로 AI에 전달
    - > 이 함수를 제네릭 기반으로 개선해줘.
- Native Diffing - 코드 변경 사항 시각적 확인
  - AI가 제안한 수정 사항은 IDE의 Diff 뷰어에서 원본과 비교 가능.

11.5 - 실전 활용 팁

Gemini CLI가 유용한 이유

초대형 1M 컨텍스트 윈도우
- 현대 AI 도구 중 최대 규모의 컨텍스트 윈도우를 지원해 대형 코드베이스 분석이나 복잡한 문서 비교처럼 기존 도구로는 비용과 시간이 많이 드는 작업에서 효율이 뛰어남
  - 수백 개 파일로 구성된 레거시 프로젝트 구조 분석
  - 다수의 API 설명서, 기술 문서를 동시에 교차 비교
  - 테스트 스위트 전체의 패턴 및 커버리지 문제 분석
  - 복잡한 아키텍처의 전반적 흐름 파악
경제성 및 넉넉한 무료 티어
- Gemini API는 무료 사용 한도가 특히 넉넉해 테스트 및 반복 분석에 적합함.
AI 터미널 도구 간 상호보완
- 세 도구를 함께 사용하면 효율을 극대화 할 수 있다.
  - Claude Code : 정교한 분석, 고품질 reasoning 중심 작업
  - Codex : 정밀한 코드 해석, 작업 수행 능력 탁월
  - Gemini CLI : 대형 컨텍스트, 문서나 코드 병합 분석, 경제성

1M 컨텍스트 윈도우 활용 전략

단순히 ‘많은 파일을 넣을 수 있다’ 는 수준을 넘어 복잡한 분석을 한 세션에서 끝낼 수 있다는 점이 핵심이다.

대형 코드베이스 전체 구조 분석
- 일반 도구라면 여러 번 나누어 수행해야 하지만, Gemini CLI는 전체 맥락을 통합해 분석
여러 기술 문서 비교 분석
- 문서 교차 비교 가능
테스트 스위트 전체 패턴 분석
- 테스트 누락, 중복, 취약점 등 구조적 문제를 한 번에 찾아냄

컨텍스트 활용 최적화 팁
1. 관련 파일을 처음부터 묶어서 로드하기
  - 프로젝트 단위로 구조를 한 번에 이해시키는 것이 중요
2. /status명령으로 토큰 사용량 모니터링
3. 체크포인트를 기반으로 작업하기
  - 중간 상태 저장 : /chat save auth-analysis
  - 저장된 세션 불러오기 : /chat resume auth-analysis

Study

AI CLI 코딩 자율학습단 20기

This post is licensed under CC BY 4.0 by the author.