title: “Gemini CLI 활용 가이드” published: 2025-10-31

Gemini CLI 사용 설명서: 당신의 AI 개발 파트너

안녕하세요! 저는 여러분의 터미널에서 함께 일하는 AI 개발 파트너, Gemini CLI입니다. 저는 단순히 대화만 나누는 챗봇이 아니라, 실제 도구를 사용하여 여러분의 파일 시스템과 직접 상호작용하며 개발 작업을 돕습니다.

이 가이드는 여러분이 저를 100% 활용하여 개발 생산성을 극대화할 수 있도록 돕기 위해 만들어졌습니다. 제가 어떤 요청에 어떻게 반응하는지, 그리고 어떤 방식으로 요청하는 것이 가장 좋은지 예시와 함께 알아보겠습니다.

제가 어떻게 일하는지 이해하면 저를 더 잘 활용할 수 있습니다.

맥락 우선주의 (Context First): 저는 섣불리 추측하지 않습니다. 코드를 수정하거나 새로운 코드를 작성하기 전에, 항상 read_file이나 search_file_content 같은 도구를 사용해 주변 코드를 읽고 프로젝트의 스타일, 구조, 규칙을 먼저 파악합니다.
도구 기반 작업 (Tool-Driven): 저는 채팅만 하는 AI가 아닙니다. list_directory, read_file, write_file, run_shell_command 등의 실제 도구를 사용하여 여러분의 요청을 물리적으로 수행합니다. 여러분의 화면에는 제가 사용하는 도구(Tool) 호출 코드가 투명하게 공개됩니다.
점진적이고 투명한 진행 (Incremental & Transparent): 복잡한 요청에 대해서는 한 번에 모든 것을 처리하려 하지 않습니다. 보통 이해 -> 계획 -> 실행 -> 검증 의 단계를 거치며, 각 단계에서 제가 무엇을 하려는지 명확히 알려드립니다. 여러분은 제 계획을 보고 진행 여부를 결정할 수 있습니다.

가장 기본적인 작업입니다. 프로젝트 구조를 파악하거나 특정 코드를 찾을 때 유용합니다.

요청 예시:

“현재 디렉토리의 모든 *.js 파일 목록을 보여줘.” “프로젝트 전체에서 ApiService라는 단어가 사용된 곳을 모두 찾아줘.”
Gemini의 작업 과정:
1. 첫 번째 요청에 대해, 저는 glob 도구를 사용해 패턴에 맞는 파일 목록을 찾습니다.
  - tool_code: print(default_api.glob(pattern='**/*.js'))
2. 두 번째 요청에 대해, search_file_content 도구를 사용해 파일 내용 전체를 검색합니다.
  - tool_code: print(default_api.search_file_content(pattern='ApiService'))
결과물: 요청한 파일 목록이나, 검색어가 포함된 파일 경로, 라인 번호, 해당 라인의 내용이 출력됩니다.

처음 보는 코드나 복잡한 로직을 이해해야 할 때 시간을 절약할 수 있습니다.

요청 예시:

“src/utils/auth.js 파일의 createToken 함수가 무슨 역할을 하는지 설명해줘.”
Gemini의 작업 과정:
1. 먼저 해당 파일의 내용을 정확히 파악하기 위해 read_file 도구를 사용합니다.
  - tool_code: print(default_api.read_file(absolute_path='/path/to/your/project/src/utils/auth.js'))
2. 파일 내용을 분석하여 createToken 함수의 목적, 파라미터, 반환 값, 그리고 주요 로직을 파악합니다.
결과물: “이 함수는 사용자의 ID와 이메일을 입력받아, JWT(JSON Web Token)를 생성하는 역할을 합니다. 토큰의 유효기간은 1시간으로 설정되어 있으며, process.env.JWT_SECRET을 비밀 키로 사용합니다.” 와 같이 분석된 내용을 한국어로 명확하게 설명해 드립니다.

가장 강력한 기능 중 하나입니다. 단순 반복 작업을 자동화하고 코드 품질을 개선할 수 있습니다.

요청 예시:

“src/api/user.js 파일의 getUserInfo 함수를 async/await 구문을 사용하도록 리팩토링해줘.”
Gemini의 작업 과정:
1. (이해) read_file로 user.js 파일의 현재 코드를 읽습니다.
2. (계획) 기존 Promise 기반 코드를 async/await으로 어떻게 변경할지 계획하고, 변경될 코드 내용을 사용자에게 제시하며 동의를 구합니다.
3. (실행) 사용자가 동의하면, replace 도구를 사용해 기존 코드 블록을 새로운 async/await 코드 블록으로 안전하게 교체합니다.
  - tool_code: print(default_api.replace(file_path=..., old_string=..., new_string=...))
결과물: 파일이 성공적으로 수정되었다는 메시지가 출력됩니다. 여러분의 소스 파일에는 async/await으로 변경된 코드가 실제로 적용되어 있습니다.

테스트 실행, 서버 구동, 패키지 설치 등 터미널 명령어를 저를 통해 실행할 수 있습니다.

요청 예시:

“npm 테스트 실행해줘.” “이 프로젝트에 axios 라이브러리를 추가해줘.”
Gemini의 작업 과정:
1. run_shell_command 도구를 사용해 요청된 명령을 실행합니다.
2. 안전장치: 파일 시스템을 변경하거나 외부 스크립트를 실행하는 명령어의 경우, 실행하기 전에 “이 명령은 npm install axios를 실행하여 package.json과 node_modules를 변경합니다.” 와 같이 어떤 작업을 수행하는지 설명하고 사용자에게 확인을 받습니다.
  - tool_code: print(default_api.run_shell_command(command='npm test'))
  - tool_code: print(default_api.run_shell_command(command='npm install axios'))
결과물: 터미널에서 직접 명령을 실행했을 때와 동일한 stdout과 stderr 결과가 출력됩니다.

구체적으로 요청하세요: “코드 수정해줘” 보다는 “auth.js 25번째 줄의 로그인 로직에 try-catch 에러 핸들링을 추가해줘” 와 같이 구체적인 파일명, 함수명, 라인 번호를 언급하면 훨씬 빠르고 정확하게 작업할 수 있습니다.
파일 경로를 알려주세요: 제가 파일 시스템을 탐색하는 시간을 줄일 수 있도록, 가능한 한 파일의 전체 또는 상대 경로를 알려주시면 좋습니다.
기억해달라고 말하세요: “앞으로 *.test.js 파일은 항상 jest 스타일로 작성해줘” 와 같이 특정 규칙을 save_memory 도구를 통해 제게 기억시킬 수 있습니다.
과정을 신뢰해주세요: 제가 파일을 읽거나 질문을 하는 것은 더 나은 결과를 드리기 위한 과정입니다. 잠시만 기다려주시면 더 정확한 결과물로 보답하겠습니다.

이제 여러분은 Gemini CLI와 함께 일할 준비가 되었습니다. 지금 바로 위 예시처럼 요청하여 여러분의 첫 번째 AI 기반 개발을 시작해보세요!

작성일: 2025-07-28