Gemini CLI 사용법 - QnA 게시판 만들기(feat. SpecKit)

in AI on Basic


  • 안녕하세요. 이번 글은 Gemini CLI, SpecKit, Supabase, Vercel을 활용해 QnA 시스템을 구현하는 내용에 대해 작성한 글입니다.
  • Gemini CLI 설정부터 SpecKit을 사용하는 흐름, Supabase 설정 및 UI 개선하는 과정을 담았습니다.
  • 키워드 : Gemini CLI 사용법, Gemini CLI with SpecKit, Supabase, Vercel, Gemini Code Assist



Gemini CLI

소개

  • Gemini CLI는 Google의 AI 모델(Gemini)을 CLI 환경에서 사용할 수 있게 해주는 개발자 도구
  • 최근 터미널 기반의 제품이 많이 나오는데, 직접 사용해보면 생산성이 많이 좋아지는 것을 느낄 수 있음
  • Gemini 모델의 장점 때문에 Gemini CLI를 쓰게 됨
    • (1) 긴 컨텍스트 : 컨텍스트를 많이 넣을 수 있기 때문에 복잡한 작업, 많은 컨텍스트가 필요할 때 유리
    • (2) 가격 : Gemini 모델의 가격은 다른 모델의 가격 대비 엄청 저렴함(특히 Gemini Flash Lite가 저렴해서 자주 사용함)
  • 공식 문서, Docs

Gemini CLI 설치

  • Gemini CLI는 Node.js 환경에서 동작하므로, 사전에 Node.js가 설치되어 있어야 함
    • 만약 Node가 설치되어 있지 않다면 Node.js 페이지를 확인해서 Node 설치

  • npm으로 글로벌하게 설치

      npm install -g @google/gemini-cli

Gemini CLI 실행

  • 터미널에서 gemini 입력 후 엔터
    • 만약 첫 실행이면 인증 방식을 선택하게 됨
    • 구글 계정 로그인, API Key 방식, 구글 클라우드의 Vertex AI를 통해 인증할 수 있음
    • 저는 Gemini를 구독하고 있어서 구글 로그인으로 선택함

  • /model을 입력하면 모델을 선택할 수 있음
    • Pro (gemini-3-pro-preview, gemini-2.5-pro)로 설정

Gemini CLI 주요 명령어

명령어설명
/help사용 가능한 명령어 목록 확인
/model모델 선택 (gemini-3-pro 등)
/memory show현재 로드된 GEMINI.md 내용 확인
/memory refreshGEMINI.md 파일 다시 로드
/memory add <text>메모리에 텍스트 추가
/chat대화 저장/불러오기/공유
/chat save <tag>현재 대화를 태그로 저장
/chat resume <tag>저장된 대화 이어서 진행
/mcpMCP 서버 목록 및 상태 확인
/tools사용 가능한 도구 목록
/stats토큰 사용량, 세션 시간 등 통계
/restore체크포인트로 롤백 (파일 변경 전 상태)
/clear터미널 화면 초기화 (Ctrl+L)
/compress대화 컨텍스트를 요약해서 토큰 절약
/copy마지막 응답을 클립보드에 복사
/settings설정 편집기 열기
  • stats 입력시 아래와 같이 Session의 통계 정보를 제공함

  • Extensions
    • 다양한 Extensions이 존재하며, 설치하고 싶으면 아래와 같이 실행(나노바나나 Extension)
      gemini extensions install https://github.com/gemini-cli-extensions/nanobanana

GEMINI.md 설정

  • GEMINI.md는 Gemini CLI에게 프로젝트 Context와 작업 규칙(Rules)을 알려주는 설정 파일
    • 이 파일에 작성한 내용은 모든 대화에서 시스템 프롬프트처럼 적용됨
  • Gemini CLI는 여러 위치의 GEMINI.md를 자동으로 찾아서 합쳐줌
    • 아래 순서대로 로드되며, 모든 파일의 내용이 합쳐짐. 같은 항목에 대해 충돌이 있으면 하위 파일이 우선 적용됨(프로젝트가 글로벌보다 더 우선 적용)
      # 1) 글로벌(모든 프로젝트 공통) : 공통 규칙, 한국어 사용 등
  ~/.gemini/GEMINI.md      
	
  # 2) 프로젝트 루트 : 기술 스택, 구조 위주
  /project-root/GEMINI.md 
	
  # 3) 하위 디렉토리(해당 폴더에서 작업할 경우)
  /project-root/src/GEMINI.md
  • 현재 로드된 컨텍스트는 /memory show 명령어로 확인할 수 있으며, CLI 하단에 로드된 파일 개수가 표시됨
  • GEMINI.md에 자주 들어가는 내용
    • 기술 스택 : Python 3.13
    • 코딩 컨벤션 : 네이밍 컨벤션
    • 프로젝트 구조 : 폴더 설명
    • 에러 처리 방식, API 호출 패턴
    • 금지 사항 : 특정 라이브러리 사용 금지
    • 참고 문서 : @로 외부 파일 import 가능

  • 다른 파일을 Import해서 불러오고 싶을 때는 @을 사용함. 프로젝트 문서나 스타일 가이드를 분리해서 관리할 때 유용함

      # GEMINI.md 
	
  ## Project Context 
  @docs/architecture.md 
  @docs/api-spec.md
  • GEMINI.md를 수정했으면 /memory refresh로 반영해야 함
  • 컨텍스트가 길다고 좋은 것은 아니므로 이 파일도 계속 관리해야 함



SpecKit을 활용한 SDD 개발

소개

  • SpecKit은 GitHub에서 만든 오픈소스로 SDD(Spec Driven Development) 도구
    • AI 코딩 에이전트(Gemini CLI, Claude Code 등)와 함께 사용하도록 설계됨
  • 만들어진 계기
    • AI에게 그냥 A 만들어줘라고 하면 의도와 다르게 나오거나 아키텍처가 엉망인 경우가 많음. 이 문제를 해결하기 위해 SpecKit은 코드 작성 전에 Spec을 정의하고 이를 기반으로 AI가 구현하도록 유도함
  • 이 Spec을 사람이 리뷰하면 되고, 리뷰하는 과정도 이 도구 사용법 안에 자연스레 존재함
    • 코드보다 이 Spec을 더 잘 관리하고, 잘 작성하는 것이 중요하다는 의견이 있는데, 저도 동의함. 기본적인 문서 작성이 더 중요해지는 시기
  • Workflow 흐름
    • 크게 6단계로 설명할 수 있음
    • (1) Specify : 기능 요구사항 정의(기술 스택이 아닌 무엇을 만들지)
    • (2) Clarify : 애매한 부분, 의사결정이 필요한 부분을 질문하며 구체화
    • (3) Plan : 기술 스택, 아키텍처 등 계획을 세움
    • (4) Tasks : Plan을 기반으로 구현할 Task 생성
    • (5) Analyze : Spec과 Task의 일관성 검증
    • (6) Implement : Task 기반으로 코드 구현

SpecKit 설치하기

  • Python의 uv 설치

      curl -LsSf https://astral.sh/uv/install.sh | sh

  • SpecKit 글로벌 설치

      uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

SpecKit 프로젝트 설정

  • SpecKit 프로젝트 초기 설정

      specify init ask-kyleschool --ai gemini

  • 만약 이미 폴더가 생성되어 있고, 현재 폴더에서 설정하고 싶은 경우

      cd existing-project 
  specify init . --ai gemini

  • 이제 .gemini 폴더와 .specify 폴더를 보면 SpecKit 관련 파일들이 생성된 것을 볼 수 있음

  • Gemini CLI에서도 커맨드가 보임

SpecKit을 활용한 개발

  • 위에서 소개한 6단계를 실제로 진행
단계명령어설명
1. Specify/speckit.specify기능 요구사항 정의
2. Clarify/speckit.clarify애매한 부분 구체화
3. Plan/speckit.plan기술 스택, 아키텍처 계획
4. Tasks/speckit.tasks구현할 태스크 생성
5. Analyze/speckit.analyzeSpec-Task 일관성 검증
6. Implement/speckit.implement코드 구현

Specify로 요구사항 구체화

/speckit.specify "SQL 강의를 진행하는데, 학생들이 자유롭게 질문을 남기면 AI가 자동으로 답변을 남겨주는 플랫폼을  만들고 싶어."
  • 조금 시간이 지나면 Branch, Spec이 완성됨
    • 여기서 디자인적 요소는 제외하고 기능 구현에 집중함

Clarify를 통해 구체화

  • 이제 clarify를 입력해서 애매한 부분에 대해 구체화를 진행
/speckit.clarify
  • 아래 화면처럼 질문들이 나타나고, 답변하면 됨

  • “Short. supabase를 사용하고 Social Login을 진행해”라고 답변함
  • 이번엔 모델 질문

  • Gemini 2.5 Flash Lite를 사용하라고 답하고, 다른 질문들도 답변하고 이제 모두 Clarify 됨

Plan : 계획 생성

/speckit.plan
  • plan이 모두 세워짐

Tasks : Task 생성

  • 이제 tasks 실행
/speckit.tasks
  • 이제 tasks 생성 완료

  • 생성된 tasks를 확인해보니 다음과 같음

Analyze : Spec과 Task의 일관성 검증

/speckit.analyze
  • SpecKit이 분석(analyze) 도중 Critical 이슈를 감지하면, 사용자에게 해결 방향을 물어봄

  • Critical 이슈를 해결하기 위해 Tasks.md 수정하라고 지시함
    • Constitution Alignment Issue
    • SpecKit 기본 원칙(constitution)에 “테스트 먼저 작성(Test-First)”이 필수로 되어 있음
    • 근데 현재 tasks.md를 보니 테스트 작성 태스크가 없거나 너무 뒤에 있음 (T025/T026이 마지막 폴리싱 단계)
    • 요약하면 테스트 먼저 써야 하는데 구현 태스크만 잔뜩 있어서 이슈 제시

  • 위와 같이 tasks.md를 수정함
    • Test tasks 추가 : Phase 3, 4, 5에 테스트 Task 추가 (Test-First 원칙 준수)
    • RLS task 명시 : “같은 강의의 질문만 보이게” 가시성 규칙 명확히 함 (FR-009)
    • Input Sanitization : 보안용 입력값 검증 Task 추가 (T012)
    • Dependencies 업데이트 : 테스트 도구 설치(T002)

Implement : 코드 구현

  • 이제 코드 구현. 이 작업은 앞선 작업들보다 시간이 더 소요됨
/speckit.implement
  • 약 13분 정도 소요됨. 이 시간엔 위에서 작성된 Spec 문서를 다시 확인하거나 인프라 작업을 준비함(DB 등)

  • 코드 구현 후, 이제 어떻게 진행하면 좋을지 물어봄(=인프라 작업 등의 안내를 받기 위해)



환경 설정

  • 앞서 구현한 코드를 실행하기 위해 Supabase 및 Gemini API 설정 진행

Supabase 설정

  • Supabase 가입 후 새 프로젝트 생성

  • 프로젝트 Settings - API Keys - Legacy anon, service_role API Keys를 누르면 anon_key를 확인할 수 있음

  • Supabase URL은 Settings - Data API - Project URL에서 확인할 수 있음

  • 위 두 키를 .env.local에 저장함. 이 파일은 .gitignore에 추가되어야 함(Push 방지)

Gemini API 설정

  • AI Studio에서 생성할 수 있음
  • 홈페이지 접속 후 Get API Key - API 키 만들기 - 이름 설정하면 Key가 저장됨
  • Supabase와 마찬가지로 Gemini API Key를 .env.local에 저장함

Supabase - Database 생성

  • supabase/migrations/20251220_init_schema.sql의 내용을 Supabase SQL Editor에서 실행

  • 이제 필요한 Database가 생성됨

소셜 로그인 설정

  • 소셜 로그인 설정을 하기 위해서 구글 클라우드 계정이 필요함
    • 만약 이 과정이 번거로우면 처음엔 소셜 로그인 설정을 추가하지 않아도 무방함. 하지만 서비스로 만들 땐 소셜 로그인을 지원하는 것이 필요함
  • 구글 클라우드 계정을 하나 생성한 후, Auth 페이지로 이동
  • 만약 처음 생성했다면 아무것도 존재하지 않고, 시작하기 버튼을 클릭해야 함

  • 앱 정보를 입력하고 나머지도 순차적으로 입력 후 저장
    • 대상 : 외부

  • 그 후, 클라이언트를 클릭한 후, 클라이언트 만들기 클릭

  • 클라이언트를 만들면 다음과 같이 설정이 저장됨. JSON 다운로드를 해두는 것을 추천(잃어버리지 않도록 주의. 다운로드 폴더에 그대로 두지 않기)

  • 이제 Supabase로 돌아와서 Authentication - Sign In / Providers - Google을 선택

  • Enable Sign in with Google을 설정하고 위에서 만든 클라이언트 id와 클라이언트 secret 값을 붙여넣기
    • 하단에 있는 Callback URL 값은 이후에 사용할 예정이므로 복사 클릭

  • 다시 구글 클라우드의 Client쪽에 다음과 같이 추가
    • 승인된 JavaScript 원본 : 실행시킬 URL 입력. 지금은 배포하지 않고 제 로컬에서 실행할 예정이라 localhost:3000만 추가함
      • 나중에 배포하면 배포한 URL 웹페이지를 입력하면 됨
    • 승인된 리디렉션 URI : 위에 Google 로그인에서 복사한 Callback URL 입력



개발 결과 확인

  • 이제 인프라 설정이 완료되었으므로, 터미널에서 아래 명령어 실행해서 개발 결과 확인
npm run dev
  • localhost:3000으로 접속하면 다음과 같이 뜸

  • 구글로 로그인을 시도하니 정상적으로 로그인 완료
  • 로그인 후 닉네임 설정을 하게 됨

  • 강의 페이지로 이동

  • ‘BigQuery 쿼리를 실행하기 위한 기본적인 쿼리 구성 요소를 알려주세요’라고 질문함

  • 그 결과 질문이 올라옴

  • 답변은 다음과 같이 달림. 단, 마크다운 설정이 필요할 것 같음

  • 만약 실행하는 과정에서 오류가 발생하면 Gemini CLI에게 오류를 보내고 수정하라고 가이드하면 됨. 만약 반복된다면 전체적으로 점검하라고 요청하는 것을 추천



UI 개선

새로운 Spec을 통해 디자인 개선하기

  • 기능 구현은 되었고, 디자인을 개선하기 위해 다시 Spec을 작성함

  • 위에서 진행한 것처럼 clarify, plan, tasks, analyze, implement를 실행한 후 기다림
    • 이제 마크다운을 잘 표현하고, 디자인이 살짝 개선됨

더 자세한 지시를 통해 디자인 개선하기

  • 만들어진 디자인이 마음에 들지 않아 어떻게 개선할지 고민하다가, Claude Code의 frontend-design 스킬을 참고해서 개선하라고 지시함

  • GEMINI.md 파일에 아래 내용을 추가함

      ## Frontend Design
  - Please refer to @frontend-design.md when implementing frontend designs
  • GEMINI.md를 수정한 후, 해당 지시를 기반으로 디자인을 개선하라고 지시함

  • 처음 버전보다 더 세련된 느낌. 만약 내가 원하는 방향성이 있다면 디자인 레퍼런스를 구체적으로 줄수록 만족스러운 결과가 나올 수 있음

Gemini CLI에게 아이디어 문의

  • 이제 또 무엇을 하면 좋을지 아이디어를 물어봤더니, 좋은 아이디어를 줬음

  • 위 내용을 모두 모아서 하나의 Spec으로 정의해서 구현해달라고 지시함
    • 강의 클릭시 대기 시간에 system_log 형식으로 구현함



Gemini Code Assist를 활용한 AI 코드 리뷰

  • 이제 GitHub에 Push함. 처음 작업이라 main에 바로 Push했으나, 그 이후엔 브랜치를 새롭게 만들어서 확인하는 것을 추천함
  • Gemini Code Assist를 설치하면 GitHub에서 Pull Request가 발생할 때 코드를 Gemini가 리뷰해줌. 이 설정을 해두는 것을 추천

설정

  • 로그인을 완료한 후, 사용할 GitHub Repository를 추가

AI 코드 리뷰 결과

  • 이렇게 설정한 후, Pull Request를 하면 아래와 같이 리뷰가 달림(아래 리뷰는 다른 Repo에서 Gemini Code Assist가 리뷰한 내용을 가져옴)



Vercel 배포

  • Supabase와 Vercel이 잘 통합되어 있으므로, Vercel을 통해 배포하는 것을 추천
  • 이 부분에 대해 글을 작성할 예정은 아니였지만, 간단하게라도 가이드를 남겨봄
  • Vercel - New Project를 누르면 GitHub에서 Import를 할 수 있음

  • Supabase URL, Anon Key를 추가하면 어렵지 않게 배포할 수 있음
  • Vercel 배포가 완료되면 새로운 URL이 생성됨. 이 URL을 Google Cloud OAuth(위에 소셜 로그인 부분)에 가서 승인된 JavaScript 원본에 Vercel URL을 추가해야 함
  • 그리고 Supabase에서도 URL 설정을 추가해야 함
    • Supabase > Authentication > URL Configuration에서 Site URL을 Vercel URL로 변경



후기

  • Gemini CLI도 많이 사용하면서 도구에 적응하게 됨. 이런 도구들은 실제로 써보고, 피드백 루프를 돌리는 과정이 필요함
  • Gemini CLI의 Release Notes를 보면 새로운 기능들이 계속 생기고 있음. 앞으로 계속 더 발전할 것 같음
  • Claude Code와 Gemini CLI 둘 다 사용하게 되었는데, 필요에 맞게 사용할 수 있도록 계속 시도해볼 예정
    • Gemini CLI가 컨텍스트가 많기 때문에 핵심 AI 에이전트로 쓰고, Gemini CLI에서 Claude Code나 Codex를 실행하게 하는 것도 방법이고, 이미 이런 시도를 하는 분들이 계심
    • AI 에이전트 도구들의 설정을 동일하게 저장해서 (예를 들어 AGENT.md를 만들어서) 관리하는 것이 필요할 듯. 새로운 도구로 이사하는 것이 번거롭게 느껴질 수 있음



이 글은 GDE 프로그램에서 진행한 AI Sprint에 참여하며 작성한 글입니다.

Google Cloud credits are provided for this project. #AISprint

카일스쿨 유튜브 채널을 만들었습니다. 데이터 분석, 커리어에 대한 내용을 공유드릴 예정입니다.

PM을 위한 데이터 리터러시 강의를 만들었습니다. 문제 정의, 지표, 실험 설계, 문화 만들기, 로그 설계, 회고 등을 담은 강의입니다

이 글이 도움이 되셨거나 의견이 있으시면 댓글 남겨주셔요.

Buy me a coffeeBuy me a coffee



© 2017. by Seongyun Byeon

Powered by zzsza