[AI] Gemini CLI를 더 알차게 사용해보자

🛠️ 개발 환경

• 💻 OS: MacOS
• 👾 Github: gemini-cli-commands

⚽️ 목표

가난한 취준생은 오늘도 Google AI Pro 플랜을 알차게 사용하기 위해 고군분투 중이다. 평소에는 oh-my-opencode를 통해 기초 개발을 진행하다가, 토큰 제한에 걸리면 Gemini CLI로 넘어오고, 시각적인 뷰를 보면서 개발해야 할 때는 Google Antigravity로 넘어가는 방식을 섞어가며 힘들게 개발을 이어가고 있다.

 

이 과정을 반복하다 보니 문득 ‘Gemini CLI 안에서 oh-my-opencode(OmO)의 워크플로우를 어떻게든 흉내 내볼 수 없을까?’라는 생각이 들었다.

 

OmO처럼 구체적인 계획을 먼저 작성시키고, 그 계획을 토대로 코드를 짜게 만드는 방식이 너무 마음에 들었기 때문이다. 그렇게 내 목표는 OmO의 핵심인 Prometheus(Plan Builder)와 Atlas(Plan Executor)의 역할을 Gemini CLI라는 단일 환경에서 간접적으로나마 구현해 보는 것으로 잡혔다.

🔍 의문과 증명

oh-my-opencode 개발팀은 24,000달러(한화 약 3,500만 원)어치의 어마어마한 토큰을 태워가며 토큰 최적화와 정확도를 높이기 위해 엄청난 노력을 기울였다고 한다. 과연 무엇이 토큰을 절약하고 성능을 끌어올렸는지 먼저 살펴보자. 공식 README.md 파일에는 다음과 같은 기능이 명시되어 있다.

"/init-deep을 통해 프로젝트 전체에 걸쳐 계층적인 AGENTS.md 파일을 자동 생성하여 토큰 효율과 에이전트 성능을 동시에 잡는다."

 

즉, 에이전트가 코드를 짤 때마다 매번 프로젝트 전체를 풀 스캔하도록 시키는 것이 아닌, 요약된 핵심 지식 문서만 참조하게 만들어 불필요한 컨텍스트 로드를 막는 최적화 전략이다.

 

그렇다면, '계획 수립(Prometheus) -> 개발 진행(Atlas)'으로 이어지는 역할 분담 구조는 어떨까? 이에 대한 해답은 공식 GitHub의 Issue #1826에서 명확히 드러난다.

Q. 사용자 문제 제기
"에이전트 역할 간의 정보 전달(Hand-off)은 지연 시간을 늘릴 뿐만 아니라 토큰 소모를 배가시키고 있습니다."

A. 메인테이너 답변
"전적으로 동의합니다. 이 설계는 의도적인 트레이드오프입니다. OMO는 복잡한 개발 워크플로우를 타겟으로 하기에, 전문화로 얻는 이점(정확도)이 토큰 오버헤드를 능가한다고 판단했습니다."

 

정리하자면, 작업을 쪼개서 각기 다른 모델에게 지시사항과 컨텍스트를 전달하는 과정 자체는 오히려 더 많은 토큰을 소모한다는 것을 개발진도 인정하고 있다. 비용을 더 지불하더라도 압도적인 꼼꼼함과 정확도를 얻겠다는 의도적인 설계인 것이다.

 

하지만 Gemini CLI와 같은 단일 에이전트 환경은 에이전트 간의 '정보 전달' 과정이 필요 없다. 세션을 통해 컨텍스트를 캐싱하기 때문이다. 따라서 연속적인 작업에서는 단일 에이전트 방식이 토큰 소모량 측면에서 훨씬 유리할 수 있다는 가설이 세워진다.

 

실제로 이 가설이 맞는지 테스트를 진행해 보았다.

• 테스트1 (OmO 방식): 프로젝트 구조 제공 -> 계획 수립(PLANNING 생성) -> 계획을 바탕으로 코드 개발
• 테스트2 (단일 프롬프트 방식): 다짜고짜 프롬프트만 전달

 

테스트에 사용된 요구사항은 다음과 같이 아주 단순하게 던져보았다.

Task 등록 폼에서 '인박스 보관' 버튼 클릭 시 인박스에 추가되지 않는 버그가 있어. 수정해 줘.

테스트1(OmO 플로우)

테스트2(프롬프트만 전달)

테스트 결과 정리

구분	Reqs	Input Tokens	Cache Reads	Output Tokens	총 연산 비용 (USD)
테스트1	39	147,672	743,994	5,535	약 $0.1276
테스트2	29	176,802	922,909	2,306	약 $0.1415

테스트1에서 캐싱된 내용을 테스트2에서 일부 재사용했다는 아쉬운 점은 있지만, 그럼에도 단순 지시를 내린 테스트2가 입력 토큰을 20%가량 더 소모했다는 것을 알 수 있다.

 

비용뿐만 아니라 작업의 질에서도 큰 차이가 났다. 테스트1은 필요한 파일만 정확히 찾아 깔끔하게 문제를 해결한 반면, 뚜렷한 계획표가 없었던 테스트2 방식은 다음과 같은 문제점들을 노출했다.

1. 하네스(Harness) 문제: 작업 완료 후 테스트를 실행하지 않아서 직접 테스트 코드를 실행해보니, 통과하지 못하는 문제가 발생
2. 비효율적인 탐색: 무얼 고쳐야 할지 몰라 SearchText, ReadFile 도구를 난사하며 불필요한 파일을 엄청나게 읽음
3. 작업 시간 지연: 명확한 지시 사항과 목표가 없다 보니 에이전트가 헤매는 시간이 길어졌다.

하네스: 시스템이나 컴포넌트를 검증하기 위한 환경, 스크립트 등의 집합

🧩 구현 과정

가설 검증이 끝났으니 본격적인 구현에 들어가 보자. 앞선 테스트를 바탕으로 다음과 같은 플로우를 구축할 것이다.

1. 프로젝트 구조 및 기반 지식을 문서화하여 주입 (/init)
2. 구체적인 개발 계획 수립 (/plan)
3. 수립된 계획을 순차적으로 개발 (/work)

1. 프로젝트 정보 주입 (/init)

가장 먼저 OmO의 /init-deep과 같은 역할을 하는 /init 명령어를 구현해 보자. OmO는 프로젝트의 핵심 정보를 구조화된 마크다운으로 관리한다.

# PROJECT KNOWLEDGE BASE
## OVERVIEW
## STRUCTURE
## WHERE TO LOOK
## CODE MAP
...

나도 이 구조를 차용하기 위해, 제일 먼저 /init 커맨드 환경을 세팅했다.

mkdir -p ~/.gemini/commands
vim ~/.gemini/commands/init.toml

모든 Prompt에 대한 상세 내용은 gemini-cli-commands 리포지토리에 정리해 두었습니다. 앞으로 따로 언급하지 않을 예정이니 참고 부탁드립니다.

 

프롬프트를 작성하고 폴더로 이동해 gemini를 실행한 뒤 /init을 입력해 보았다. 하지만 기대와 달리 화면에 마크다운 텍스트만 줄줄이 출력될 뿐 실제 파일은 생성되지 않는다.

 

그 이유는 Gemini CLI의 .toml 커스텀 커맨드가 단순히 LLM에게 "어떤 포맷으로 대답할지"를 지시하는 프롬프트 템플릿에 불과하기 때문이다. 즉, LLM은 텍스트를 입력받아 텍스트를 뱉어내는 철저히 격리된 뇌 역할만 할 뿐, 내 운영체제에 접근하여 디렉토리를 만들고 파일을 쓰는 손이 없는 것이다.

 

이 '뇌'와 '손'을 연결하기 위해 반드시 도입해야 하는 기술이 바로 MCP (Model Context Protocol)다.

• Model (모델): 생각하고 코드를 짜는 AI (Gemini 등)
• Context (컨텍스트/문맥): AI가 갇혀있는 텍스트 박스 너머의 진짜 세상. 즉, 내 로컬 파일 시스템, Git 환경, 터미널 등 에이전트가 조작해야 하는 '실제 작업 환경'
• Protocol (프로토콜): 이 격리된 모델(Model)이 외부 환경(Context)의 도구들을 안전하게 호출하여 사용할 수 있게 이어주는 '연결 규약'

간략히 말해, MCP는 말만 하던 AI에게 내 로컬 환경을 직접 조작할 수 있는 권한과 도구를 쥐여주는 표준 인터페이스다. 이제 생각만 가능한 toml 명령어에 진짜 손을 달아주기 위해 MCP를 적용해 보자.

vim ~/.gemini/settings.json

설정 파일의 general 블록이 끝나는 곳 뒤에 콤마(,)를 찍고, 다음 라인에 아래 내용을 추가한다.

  "mcpServers": {
    "local_filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "{GIT_PROJECT_DIR}"
      ]
    }
  }

여기서 {GIT_PROJECT_DIR}에는 ~/dev/git/ 와 같이 권한을 부여할 프로젝트의 최상위 절대 경로를 넣으면 된다.

~/와 같이 너무 많은 경로에 대한 권한을 줄 경우 문제가 생길 수 있으니 조심해야 한다.

 

설정을 저장하고 Gemini CLI를 재시작한 뒤 다시 /init을 실행하면, AI가 알아서 프로젝트 내부에 있는 파일들을 분석하고 다음 파일들을 수정 및 생성해 준다.

• /GEMINI.md: AI가 작업 전 반드시 숙지해야 할 시스템 가이드라인
• /.gemini/docs/STRUCTURE.md: 프로젝트 구조, 기술 스택, 핵심 코드 맵핑 지식
• /.gemini/docs/DOCUMENT.md: 프로젝트 아키텍처 및 버전 히스토리

2. 계획 수립 (/plan)

프로젝트의 기반 지식을 모두 주입했으니, 요구사항을 바탕으로 구체적인 계획을 수립할 차례다.

이 역시 OmO의 포맷을 차용했다.

# Execution Plan
## 1. Goal
## 2. Scope (In-Scope / Out-of-Scope)
## 3. Architecture Impact
## 4. Execution Plan (Phase 1, 2, 3...)
## 5. Risk Mitigation
## 6. Final Verification Wave

이 구조를 생성해 내는 명령어 역시 리포지토리에 추가해 두었다.

vim ~/.gemini/commands/plan.toml

이제 구현하고 싶은 기능이나 버그 수정이 있다면, CLI 창에 대고 이렇게 질의하면 된다.

/plan Task 등록 폼에서 인박스 보관 버튼 클릭 시 인박스에 추가되지 않는 버그가 있어. 수정해 줘.

명령을 내리면 AI가 현재 프로젝트 경로를 기준으로 /.gemini/docs/PLANNING.md 파일을 생성하고, 각 Phase별로 잘게 쪼개진 체크리스트(- [ ])를 작성해 준다. 본격적인 코딩을 시작하기 전, 작성된 계획 문서가 내 의도와 맞는지 한 번 검토하는 것을 강력히 추천한다.

3. 개발 진행 (/work)

마지막으로, 수립된 PLANNING.md 파일의 체크박스를 위에서부터 하나씩 지워가며 실제 코드를 작성할 /work 명령어를 만들어 주면 파이프라인이 완성된다.

vim ~/.gemini/commands/work.toml

💨 전체 워크플로우 요약

이렇게 구축된 환경에서의 개발 흐름은 다음과 같다. OAuth의 경우 그냥 사용하면 되지만, API Key를 사용하는 경우, 다음과 같이 구성하는게 좋다. 다음 모델을 수동으로 수정하기 귀찮을 경우, plan.toml, work.toml 파일에 model 항목을 추가해주면 된다. 구체적인 내용은 리포지토리의 auth-api 브랜치의 내용을 참고하면 된다.

• plan: gemini-3.1-pro
  • 구체적인 계획 수립이 필요하므로 고성능 모델을 할당하는 것이 좋음
• work: gemini-3-flash
  • 계획을 구체적으로 수립하였기에, 개발을 빠르게 진행하기 위해 flash 모델을 할당하는게 좋음
• 테스트 해본 결과 OAuth로 로그인한 경우, toml 파일에 모델을 지정해도 그 모델을 사용하지 않으니 참고 바랍니다.

# 프로젝트 정보 초기화 및 지식 베이스 구축 (최초 1회 또는 구조 변경 시)
/init
# 깨끗한 상태로 세션 초기화
/clear

# 생성된 /.gemini/docs/PLANNING.md 파일 내용 검토
/plan {요구 사항 작성}

# 컨텍스트 압축 또는 초기화로 토큰 확보
/compress (또는 /clear)
# 계획표에 따라 실제 코드 구현 및 체크박스 업데이트 반복
/work

# 작업 완료 후 변경된 내용을 도메인 단위로 묶어 자동 커밋 & 푸시
/git

🚨 주의사항

1. 하네스(Harness)와 인간의 개입

가장 주의해야 할 점은 결국 사람이 중간중간 개입하여 검토해야 한다는 것이다. 단일 에이전트는 세션 내내 동일한 컨텍스트를 유지하므로, 한 번 잘못된 방향으로 코드를 짜기 시작하면 그 '잘못된 지식'까지 캐싱되어 연쇄적인 오류를 낼 확률이 높다. 따라서 AI가 작성한 계획 문서는 /work를 돌리기 전에 반드시 한 번씩 점검해야 한다.

2. .gitignore 파일 무시 이슈

대부분의 AI 에이전트 도구(Tool)들은 기본적으로 .gitignore에 등록된 규칙을 따른다. 프로젝트 루트의 .gitignore 파일에 .gemini/ 폴더를 무심코 등록해 버리면, 에이전트가 애써 만든 PLANNING.md나 STRUCTURE.md를 스스로 읽지 못하는 불상사가 발생할 수 있으니 파일 관리 시 유의해야 한다.

🤔 회고

단일 에이전트 환경이 가지는 명확한 장점과 치명적인 단점을 동시에 깨달을 수 있는 뜻깊은 삽질(?)이었다. 특히 컨텍스트 캐싱(Caching)이라는 기술이 가져다주는 득과 실을 확실히 체험했다.

 

그래도 언젠가 돈을 많이 벌게 되면 여러 AI 프로바이더를 동시에 구독해서, 각기 다른 역할을 수행하는 '나만의 완벽한 다중 AI 에이전트 팀'을 구성해 자율 개발을 시켜보고 싶다.