어쩐지 오늘은

안녕하세요. 이번 글은 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 refresh
      GEMINI.md 파일 다시 로드
    
/memory add <text>
      메모리에 텍스트 추가
    
/chat
      대화 저장/불러오기/공유
    
/chat save <tag>
      현재 대화를 태그로 저장
    
/chat resume <tag>
      저장된 대화 이어서 진행
    
/mcp
      MCP 서버 목록 및 상태 확인
    
/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.analyze
      Spec-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가 리뷰해줌. 이 설정을 해두는 것을 추천
설정
Gemini Code Assist GitHub App 페이지 이동 -> Configure 클릭
로그인을 완료한 후, 사용할 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

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

댓글