Antigravity CLI를 사용한 사양 기반 개발: 스킬 및 MCP를 사용한 구조화된 에이전트 워크플로

1. 소개

MVP의 바이브 코딩은 빠르지만, 벽에 더 많은 프롬프트를 던져 기능을 추가하면 프로젝트가 깨집니다. AI 지원 개발에 구조와 실제 컨텍스트를 도입할 방법이 필요합니다. 이때 터미널에서 실행되는 AI 코딩 에이전트인 Antigravity CLI가 도움이 됩니다. 이 모델은 자체적으로 코드베이스를 이해하고, 명령어를 실행하고, 파일을 수정할 수 있습니다. 진정한 강점은 연결하는 기기에 있습니다.

• 스킬은 에이전트에게 방법론과 도메인 지식을 제공합니다. 방법론 스킬은 구조화된 개발 워크플로를 적용하고 도메인 스킬은 정확한 API 지식을 제공하여 에이전트가 환각을 일으키지 않도록 합니다.
• MCP 서버는 에이전트가 외부 시스템에 실시간으로 연결할 수 있도록 지원합니다. 이를 통해 에이전트는 오래된 학습 지식에 의존하는 대신 실제 스키마를 검사하고, 쿼리를 실행하고, 실제 데이터를 기반으로 작업을 검증할 수 있습니다.

스킬은 에이전트가 생각하는 방식을 형성하고 MCP는 에이전트가 보고 상호작용할 수 있는 대상을 형성합니다. 이러한 요소들이 함께 작동하여 범용 코딩 에이전트를 실제 데이터에 기반한 구조화된 워크플로를 따르는 에이전트로 전환합니다. 이 Codelab에서는 플러그인 설치부터 기능 제공까지 이 조합을 단계별로 안내합니다.

빌드할 항목

이 Codelab의 패턴(방법론 및 도메인 지식용 스킬 설치, 실시간 데이터 액세스를 위한 MCP 서버 연결, 사양 기반 개발 주기 실행)은 언어, 프레임워크, Google Cloud 제품과 관계없이 Antigravity CLI로 빌드하는 모든 기능에 적용됩니다. 이러한 패턴을 구체화하기 위해 이커머스 분석 대시보드에 BigQuery 통합을 추가하는 특정 예를 살펴봅니다.

시작 앱은 정적 CSV 파일에서 판매 데이터를 읽고 차트 (수익 추세, 인기 제품, 주문 상태 분석, 카테고리 실적)를 렌더링하는 FastAPI 웹 앱입니다. 결과적으로 앱은 인프라를 관리하지 않고도 대규모 데이터 세트에 대해 SQL 쿼리를 실행할 수 있는 Google Cloud의 서버리스 데이터 웨어하우스인 BigQuery에서 실시간 데이터를 쿼리합니다. 특히 thelook_ecommerce 데이터 세트에 연결하면 500개 행의 CSV에서는 제공할 수 없는 주문, 제품, 고객의 전체 카탈로그를 이용할 수 있습니다. 이 기능은 기술과 MCP의 안내에 따라 Antigravity CLI를 통해 완전히 빌드됩니다.

Antigravity CLI와 함께 사용할 에이전트 구성은 다음과 같습니다.

학습할 내용

• Cloud Shell에서 Antigravity CLI를 사용하는 방법: 실행, TUI 탐색, 슬래시 명령어 실행
• 에이전트 기술이란 무엇이며 점진적 공개 패턴 (메타데이터 → 안내 → 리소스)이 컨텍스트를 효율적으로 유지하는 방법
• 세 가지 기술 카테고리: 방법론 (초능력), 효율성 (원시인), 도메인 지식 (Google/기술)
• MCP란 무엇이며 Antigravity CLI용 원격 MCP 서버 (BigQuery MCP)를 구성하는 방법
• 사양 기반 개발 주기를 실행하는 방법: 지정 → 계획 → 구현
• (선택사항) Antigravity CLI의 하위 에이전트 작동 방식 및 관리 방법
• google-cloud-bigquery Python 클라이언트 라이브러리를 FastAPI 앱에 통합하는 방법
• (선택사항) 도메인 스킬을 사용하여 Antigravity CLI로 Cloud Run에 앱을 배포하는 방법

기본 요건

• Google Cloud 계정
• Python, REST API, 터미널 명령어에 대한 기본적인 지식

2. 환경 설정

이 단계에서는 시작 저장소를 클론하고, Google Cloud 프로젝트를 구성하고, 필요한 API를 사용 설정합니다.

Cloud Shell 열기

브라우저에서 Cloud Shell을 엽니다. Cloud Shell은 이 Codelab에 필요한 모든 도구가 사전 구성된 환경을 제공합니다. 메시지가 표시되면 승인을 클릭합니다.

Cloud Shell 열기

그런 다음 '보기' -> '터미널'을 클릭하여 터미널을 엽니다. 인터페이스는 다음과 유사해야 합니다.

이것이 기본 인터페이스가 됩니다. 상단에 IDE, 하단에 터미널이 있습니다.

작업 디렉터리 설정하기

이 Codelab의 시작 코드가 포함된 저장소를 클론합니다.

💻 터미널 셸에서 복사하여 실행합니다.

git clone https://github.com/alphinside/sdd-agy-bigquery-dashboard.git
cloudshell workspace sdd-agy-bigquery-dashboard && cd sdd-agy-bigquery-dashboard

이 저장소에는 정적 CSV 파일에서 읽어오는 완전한 작동 이커머스 대시보드 앱이 포함되어 있습니다. 이 Codelab에서는 Antigravity CLI를 사용하여 BigQuery 통합을 새로운 기능으로 추가합니다.

주요 파일 및 디렉터리는 다음과 같습니다.

• src/main.py - 대시보드 데이터를 제공하는 API 엔드포인트가 있는 FastAPI 애플리케이션
• src/data_service.py - pandas를 사용하여 CSV 파일에서 읽어오는 데이터 레이어
• src/templates/dashboard.html - Chart.js 시각화가 포함된 Jinja2 템플릿
• data/: 전자상거래 데이터의 작은 하위 집합이 포함된 정적 CSV 파일 (orders.csv, products.csv, order_items.csv)

이 앱은 간단한 읽기 전용 대시보드입니다. main.py는 API 엔드포인트를 정의하고, data_service.py는 CSV 파일을 읽고 구조화된 데이터를 반환하며, dashboard.html는 해당 데이터를 차트로 렌더링합니다. 빌드하는 BigQuery 통합은 정적 파일을 읽는 대신 실시간 데이터를 쿼리하는 모듈로 data_service.py를 대체합니다.

터미널 구성

Google Cloud 프로젝트 만들기 ( 선택사항)

❗ 이미 Google Cloud 프로젝트가 있는 경우 이 섹션을 건너뛰세요

새 프로젝트를 만들려면 왼쪽 상단의 프로젝트 선택기를 클릭하고 New Project를 클릭하여 Cloud 콘솔 UI에서 만들면 됩니다.

또는 더 빠른 방법을 원한다면 터미널에서 다음 명령어를 실행하세요.

💻 터미널 셸에서 복사하여 실행합니다.

PROJECT_ID="sdd-agy-cli-$(openssl rand -hex 5)"
gcloud projects create "$PROJECT_ID"
echo $PROJECT_ID

이렇게 하면 무작위 프로젝트 ID로 Google Cloud 프로젝트가 생성됩니다. 명령어는 생성된 프로젝트 ID를 출력합니다. 나중에 구성에서 YOUR_PROJECT_ID로 사용하세요.

터미널 활성화

이제 선택한 Google Cloud 프로젝트로 터미널을 구성해야 합니다. 다음 명령어를 실행하여 사용 가능한 프로젝트를 나열하고 선택할 프로젝트 ID를 찾습니다.

💻 터미널 셸에서 복사하여 실행합니다.

gcloud projects list

다음과 같은 목록이 표시됩니다. 사용할 프로젝트 ID를 기억하거나 복사합니다.

PROJECT_ID: alvin-exploratory-2
NAME: alvin-exploratory-2
PROJECT_NUMBER: 109790610330

이제 다음 명령어를 실행하여 터미널을 활성화하는 스크립트를 만듭니다. 직접 이 파일을 만들어도 됩니다.

💻 터미널 셸에서 복사하여 실행합니다.

cloudshell edit configure_terminal.sh

그런 다음 다음 코드를 스크립트에 복사합니다.

📄 파일을 복사하여 저장합니다.

YOUR_PROJECT_ID 값을 이전 단계에서 선택한 프로젝트 ID로 바꿉니다.

#!/bin/bash

gcloud config set project YOUR_PROJECT_ID
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
echo $GOOGLE_CLOUD_PROJECT

YOUR_PROJECT_ID를 프로젝트 ID로 바꿉니다. 이전 명령어는 Codelab 전체에서 사용할 프로젝트 ID를 환경 변수로 내보내기도 합니다. 그런 다음 파일을 저장하고 실행합니다.

💻 터미널 셸에서 복사하여 실행합니다.

bash configure_terminal.sh

참고: 터미널이나 웹페이지를 닫거나 다시 시작한 경우 터미널을 구성하기 위해 이 명령어를 다시 실행해야 합니다.

Cloud Shell 터미널 프롬프트의 작업 디렉터리 옆에 있는 노란색 텍스트를 확인하여 프로젝트가 올바르게 설정되었는지 확인합니다. 프로젝트 ID가 표시되어야 합니다.

필요한 API 사용 설정

다음으로 사용 사례 시나리오와 관련된 BigQuery와 상호작용합니다. 이 Codelab에 필요한 Google Cloud API를 사용 설정합니다.

💻 터미널 셸에서 복사하여 실행합니다.

gcloud services enable bigquery.googleapis.com

참고: API를 사용 설정하는 데 시간이 걸릴 수 있습니다. 이 작업은 프로젝트별로 한 번만 수행하면 됩니다.

이 API를 사용하면 BigQuery에 액세스할 수 있습니다. 이제 이 Codelab 시나리오를 위한 초기 데이터 세트를 준비해 보겠습니다.

3. BigQuery 데이터 세트 설정

시나리오는 다음과 같습니다. 회사에 이미 BigQuery에 저장된 전자상거래 데이터(주문, 제품, 주문 항목)가 있습니다. 주문 데이터 대시보드를 표시하는 애플리케이션을 개발하지만 현재는 프런트엔드에 집중할 수 있도록 이 데이터의 작은 CSV 추출만 읽습니다. 이제 전체 데이터 세트를 위해 BigQuery를 직접 쿼리하도록 업그레이드하려고 합니다.

이를 시뮬레이션하기 위해 Google에서 관리하는 공개 데이터 세트인 TheLook 이커머스를 사용합니다. 이 데이터 세트에는 실제와 유사한 합성 이커머스 데이터 (주문 125,000건 이상, 제품 29,000개 이상)가 포함되어 있습니다. 관련 테이블을 자체 프로젝트의 BigQuery 인스턴스로 복사하여 '회사 데이터'로 사용합니다.

Cloud Shell에는 BigQuery와 직접 상호작용하는 데 사용할 수 있는 bq CLI가 이미 있으므로 데이터를 직접 준비할 수 있습니다.

프로젝트에서 데이터 세트를 만듭니다.

💻 터미널 셸에서 복사하여 실행합니다.

bq mk --dataset $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

공개 데이터 세트의 테이블 3개를 새 데이터 세트에 복사합니다.

💻 터미널 셸에서 복사하여 실행합니다.

bq cp bigquery-public-data:thelook_ecommerce.orders $GOOGLE_CLOUD_PROJECT:thelook_ecommerce.orders
bq cp bigquery-public-data:thelook_ecommerce.order_items $GOOGLE_CLOUD_PROJECT:thelook_ecommerce.order_items
bq cp bigquery-public-data:thelook_ecommerce.products $GOOGLE_CLOUD_PROJECT:thelook_ecommerce.products

테이블이 데이터 세트에 있는지 확인합니다.

💻 터미널 셸에서 복사하여 실행합니다.

bq ls $GOOGLE_CLOUD_PROJECT:thelook_ecommerce

orders, order_items, products의 세 테이블이 표시됩니다.

   tableId     Type    Labels   Time Partitioning   Clustered Fields  
 ------------- ------- -------- ------------------- ------------------ 
  order_items   TABLE                                                  
  orders        TABLE                                                  
  products      TABLE

빠른 테스트 쿼리를 실행하여 데이터에 액세스할 수 있는지 확인합니다.

💻 터미널 셸에서 복사하여 실행합니다.

bq query --nouse_legacy_sql \
  "SELECT COUNT(*) as total_orders FROM \`$GOOGLE_CLOUD_PROJECT.thelook_ecommerce.orders\`"

+--------------+
| total_orders |
+--------------+
|       125957 |
+--------------+

주문 수가 100,000건을 초과하는 것으로 표시됩니다.

4. 초기 웹 앱 실행

앱을 업그레이드하기 전에 현재 상태로 실행하여 CSV 기반 대시보드가 어떤 모습인지 살펴보겠습니다.

uv는 Rust로 작성된 빠른 Python 패키지 및 프로젝트 관리자입니다 ( 문서). 이 Codelab에서는 속도와 단순성을 위해 이를 사용합니다. 이 튜토리얼에서 Cloud Shell을 사용하는 경우 인스턴스에 이미 사전 설치되어 있습니다. 로컬에서 설치하려면 이 튜토리얼을 참고하세요.

프로젝트 종속 항목을 설치합니다. 그러면 가상 환경도 준비됩니다.

💻 터미널 셸에서 복사하여 실행합니다.

uv sync

그 후 Python에 익숙한 경우 python 명령어를 실행하는 대신 uv 바이너리로 모든 명령어를 실행합니다. FastAPI 개발 서버를 실행합니다.

💻 터미널 셸에서 복사하여 실행합니다.

uv run uvicorn src.main:app --host 0.0.0.0 --port 8080

Cloud Shell의 웹 미리보기 기능을 사용하여 브라우저에서 대시보드를 엽니다. 웹 미리보기 버튼 (Cloud Shell 툴바의 눈 아이콘)을 클릭하고 포트 8080에서 미리보기를 선택합니다.

도움말: Cloud Shell에서 웹 미리보기를 사용하려면 Cloud Shell 툴바에서 웹 미리보기 버튼 (눈이 있는 정사각형 아이콘)을 클릭한 후 포트 8080에서 미리보기를 선택합니다.

대시보드에는 다음 네 가지 차트 패널이 표시됩니다.

• 수익 추세 - CSV 데이터의 기간에 따른 일일 수익을 보여주는 선 차트
• 수익 기준 상위 제품: 총매출을 기준으로 제품의 순위를 매기는 가로 막대 그래프
• 주문 상태 분석: 완료, 발송 완료, 처리 중, 취소, 반품 주문의 분포를 보여주는 도넛형 차트
• 카테고리 실적: 제품 카테고리별 수익을 보여주는 가로 막대 그래프

헤더에 데이터 소스: CSV 배지가 표시됩니다. 요약 카드에는 500개의 주문과 약 750개의 주문 항목에서 계산된 합계가 표시됩니다. 이는 전체 TheLook 데이터 세트의 작은 하위 집합입니다. 기간은 2023년 10월~12월로 제한됩니다.

이것이 기준 앱입니다. 이제 Antigravity CLI를 사용하여 BigQuery와 통합되도록 업그레이드하겠습니다.

참고: 지금은 Ctrl + C를 두 번 클릭하여 현재 웹 애플리케이션 프로세스를 종료합니다.

5. Antigravity CLI 설정

이 단계에서는 Antigravity CLI를 소개하고, 터미널 사용자 인터페이스를 살펴보고, 개발 워크플로를 개선하기 위해 세 가지 카테고리의 플러그인을 설치합니다. 이 과정에서 에이전트 스킬과 MCP가 무엇인지, 그리고 이러한 요소가 AI 코딩 에이전트의 기능을 어떻게 확장하는지 알아봅니다.

Antigravity CLI란 무엇인가요?

Antigravity CLI는 터미널용 Google AI 코딩 에이전트인 Antigravity의 변형입니다. Go로 빌드된 경량 터미널 사용자 인터페이스 (TUI)로, Antigravity 2.0 데스크톱 애플리케이션을 지원하는 동일한 에이전트 하네스에 연결됩니다. 터미널에서 코드베이스를 읽고, 명령어를 실행하고, 파일을 수정하고, MCP를 통해 외부 도구에 연결합니다.

이 튜토리얼에 Cloud Shell을 사용하는 경우 Antigravity CLI가 이미 사전 설치되어 있습니다. 다음 명령어를 실행하여 확인할 수 있습니다.

💻 터미널 셸에서 복사하여 실행합니다.

agy --help

다음 명령어 옵션 세부정보가 표시됩니다.

Usage of agy:
  --add-dir                       Add a directory to the workspace (repeatable) (default [])
  -c                              Short alias for --continue
  --continue                      Continue the most recent conversation
  --conversation                  Resume a previous conversation by ID
  --dangerously-skip-permissions  Auto-approve all tool permission requests without prompting
  -i                              Short alias for --prompt-interactive
  --log-file                      Override CLI log file path
  --model                         Model for the current CLI session
  --new-project                   Create a new project for this session
  -p                              Short alias for --print
  --print                         Run a single prompt non-interactively and print the response
  --print-timeout                 Timeout for print mode wait (default 5m0s)
  --project                       Project ID for the current CLI session
  --prompt                        Alias for --print
  --prompt-interactive            Run an initial prompt interactively and continue the session
  --sandbox                       Run in a sandbox with terminal restrictions enabled

Available subcommands:
  changelog       Show changelog and release notes
  help            Show help for subcommands
  install         Configure environment paths and shell settings
  models          List available models
  plugin          Manage plugins (install, uninstall, list, enable, disable)
  plugins         Alias for plugin
  update          Update CLI

Antigravity CLI 실행

이제 처음 사용하는 경우 Antigravity CLI를 설정해야 합니다. 새 터미널 탭에서 실행합니다.

💻 터미널 셸에서 복사하여 실행합니다.

agy

처음 실행하면 인증 방법을 선택하라는 메시지가 표시됩니다.

이 튜토리얼에서는 Google OAuth를 사용합니다. 로그인에 사용할 Google 계정을 선택하라는 메시지가 표시되는 URL을 열라는 메시지가 표시됩니다.

인증을 클릭한 후 Google 계정을 선택하고 Sign In을 클릭합니다.

복사할 문자열이 표시됩니다. Copy to Clipboard를 클릭하여 복사합니다.

그런 다음 아래와 같이 Antigravity CLI 프롬프트에 붙여넣습니다.

참고: Ctrl+Shift+V를 사용하거나 마우스 오른쪽 버튼을 클릭한 다음 Paste을 선택하여 터미널에 복사합니다.

그런 다음 색상 테마와 사용 약관 동의를 선택하라는 메시지가 표시됩니다.

현재 작업공간 디렉터리를 신뢰하라는 메시지도 표시됩니다. 이를 수락하면 계속 진행할 수 있습니다. 터미널에서 Antigravity CLI와 상호작용하는 기본 항목이 됩니다.

지금은 Antigravity CLI를 종료하고 다음 섹션으로 계속 진행합니다.

참고: 종료하려면 Ctrl+D 키를 두 번 누르세요.

6. 맞춤설정 - 에이전트 스킬

Antigravity CLI는 기본적으로 코드베이스를 읽고, 셸 명령어를 실행하고, 파일을 수정할 수 있습니다. 기본 제공 사양 기반 개발 워크플로가 제한적이며 특정 API에 대한 지식은 학습 데이터에 포함된 내용으로 제한됩니다. BigQuery를 기존 앱에 통합하는 작업의 경우 두 가지 격차가 나타납니다.

1. 프로세스 격차 - 구조가 없으면 Antigravity CLI가 코드를 바로 작성할 수 있습니다. 사소한 수정이라면 괜찮습니다. 여러 파일과 엔드포인트를 사용하는 기능의 경우 구현이 일관되지 않고, 극단적인 사례가 누락되고, 결정된 사항이나 이유에 대한 문서가 없습니다.
2. 지식 격차: 모델 학습 데이터에 오래된 BigQuery 클라이언트 라이브러리 패턴, 지원 중단된 API 호출 또는 잘못된 테이블 스키마가 포함될 수 있습니다. 현재 실제 데이터 세트가 어떤 모습인지 확인할 방법이 없습니다.

기술은 프로세스 격차를 해소합니다. superpowers와 같은 개발 방법론 스킬은 사양-계획-구현 사이클을 강제 적용합니다. 즉, 사양을 승인할 때까지 에이전트가 코드를 작성하지 않습니다. bigquery-basics와 같은 도메인 스킬은 현재 Google에서 유지관리하는 API 참고 리소스를 제공하므로 에이전트가 올바른 클라이언트 라이브러리 패턴을 사용합니다.

MCP 서버는 런타임에 지식 격차를 해소합니다. BigQuery MCP는 에이전트에게 실제 데이터 세트에 대한 라이브 연결을 제공합니다. 테이블을 나열하고, 열 유형을 검사하고, 샘플 쿼리를 실행할 수 있습니다. 에이전트는 추측이 아닌 실제 스키마 데이터를 기반으로 작동합니다.

이 두 가지를 자세히 알아보겠습니다.

상담사 스킬

에이전트 스킬은 전문 지식과 워크플로를 통해 AI 에이전트 기능을 확장하는 경량의 개방형 형식입니다. 각 스킬은 SKILL.md 파일(에이전트가 특정 작업을 처리하는 방식을 정의하는 머신 리더블 계약)이 포함된 휴대용 버전 관리 디렉터리입니다.

스킬 디렉터리는 다음과 같습니다.

skills/<skill-name>/
├── SKILL.md          # Required: YAML frontmatter + workflow instructions
├── scripts/          # Optional: helper scripts
├── references/       # Optional: reference implementations
├── assets/           # Optional: templates or assets
└── ...                # Any additional files or directories

기본적으로 스킬은 SKILL.md 파일이 포함된 폴더입니다. 이 파일에는 메타데이터 (최소한 이름과 설명)와 에이전트가 특정 작업을 실행하는 방법을 알려주는 안내가 포함됩니다. 스킬은 스크립트, 참고 자료, 템플릿, 기타 리소스를 번들로 묶을 수도 있습니다.

이 Codelab의 후반부에서 사용할 bigquery-basics 스킬의 SKILL.md는 다음과 같습니다.

---
name: bigquery-basics
metadata:
  category: BigDataAndAnalytics
description: >-
  Manages datasets, tables, and jobs in BigQuery. Use when you need to interact
  with BigQuery, run SQL queries, manage BigQuery resources (datasets, tables,
  views), or perform basic data ingestion and analysis.
---

# BigQuery Basics

[Detailed instructions about BigQuery APIs, SQL patterns,
 client library usage, data ingestion patterns, etc.]

YAML 프런트매터 (이름 + 설명 + 메타데이터)는 Antigravity CLI가 시작 시 로드하는 경량 메타데이터입니다. --- 아래의 마크다운 본문은 전체 명령 집합이며, Antigravity에서 BigQuery 관련 작업을 감지한 경우에만 로드됩니다.

진행 상황 공개

스킬은 컨텍스트 윈도우 포화를 방지하는 3계층 점진적 공개 패턴을 사용합니다.

1. 레이어 1 (검색): 시작 시 Antigravity는 설치된 모든 스킬의 YAML 메타데이터만 읽습니다. 스킬이 존재한다는 것만 알고 있습니다.
2. 2단계 (활성화): 작업이 스킬의 설명과 일치하면 AGY가 전체 SKILL.md를 활성 컨텍스트로 읽어옵니다. 이제 무엇을 해야 하는지 알게 되었습니다.
3. 3단계 (실행): 필요에 따라 Antigravity가 스킬의 스크립트, 예시 또는 리소스에 액세스합니다. 이제 방법을 알게 되었습니다.

관련 지식만 적절한 시간에 로드됩니다. 예를 들어 BigQuery 쿼리를 작업할 때 Cloud Run 배포용 스킬은 컨텍스트를 사용하지 않습니다.

세 가지 기술 카테고리

상담사 기술에는 다양한 유형이 있습니다. 이 Codelab에서는 각각 다른 카테고리의 스킬을 나타내는 세 가지 스킬을 사용합니다.

카테고리	기술	목적
도메인 지식	google/skills	에이전트가 특정 기술에 대해 아는 내용
방법론	obra/superpowers	개발 방법: 사양 기반 개발, 계획, 테스트를 강제 적용합니다.
효율성	JuliusBrussee/caveman	토큰을 얼마나 효율적으로 사용할지

google/skills는 Google 제품을 위해 Google에서 유지관리하는 퍼스트 파티 에이전트 기술을 제공합니다. 예를 들어 BigQuery API, Cloud Run 배포 패턴, 기타 서비스에 관한 정확하고 최신 정보를 에이전트에게 제공합니다. 도메인 기술이 없으면 에이전트는 오래되었거나 불완전할 수 있는 학습 데이터에 의존합니다. 도메인 기술은 추측을 최신 문서로 대체합니다.

obra/superpowers는 사양 기반 개발 (SDD) 워크플로의 독자적인 구현입니다. SDD 프레임워크가 없으면 상담사는 기능에 대해 설명할 때 바로 코드로 이동합니다. 이는 작은 수정에는 적합하지만 더 큰 문제에는 일관되지 않고 유지하기 어려운 결과를 초래합니다. SDD는 요구사항 명확화 → 사양 작성 → 계획 생성 → 사양에 따른 구현이라는 구조화된 사이클을 강제합니다. 각 단계에서는 검토 가능한 아티팩트가 생성됩니다. 사양을 승인할 때까지 에이전트는 코딩을 시작하지 않습니다. spec-kit, agent-skills 등 다른 SDD 프레임워크가 있으며 각 프레임워크는 지정-계획-구현 주기에 대해 서로 다른 의견을 가지고 있습니다. 이 Codelab에서는 슈퍼파워를 구체적인 예로 사용합니다. 기본 원칙 (코딩하기 전에 지정하고 계획)은 선택한 프레임워크와 관계없이 적용됩니다.

JuliusBrussee/caveman은 에이전트 출력을 최대 75%까지 압축합니다. 기술적인 내용은 그대로 유지하면서 군더더기, 인사말, 장황한 설명을 삭제합니다. 대답당 토큰 수가 적을수록 세션당 생산적인 교환이 많아지고 대답이 빨라집니다. /caveman로 활성화하거나 에이전트에게 효율적으로 대화하라고 지시합니다. 보안 경고 및 되돌릴 수 없는 작업의 경우 자동으로 사용 중지됩니다.

상담사 스킬 설치

공식 Google Skills 설치

먼저 상호작용할 필요한 Google 기술을 설치합니다. 이 튜토리얼에서는 BigQuery와 Cloud Run이라는 주요 기술 스택을 다룹니다. 따라서 이러한 스킬을 설치해 보겠습니다. npx skills 명령어를 사용하여 이를 설치합니다.

💻 터미널 셸에서 복사하여 실행합니다.

npx skills add google/skills

그러면 대화형 터미널 UI가 열리며 다양한 스킬이 있습니다. 화살표 키와 스페이스바를 사용하여 이 Codelab에 필요한 기술을 선택합니다.

bigquery-basics 및 cloud-run-basics을 찾아 스페이스를 클릭하여 선택합니다. 아래와 같이 상자가 어두운 회색으로 표시되어야 합니다.

그런 다음 에이전트 선택에서 Enter를 클릭하여 선택을 건너뜁니다. Antigravity CLI가 기본적으로 포함되어 있기 때문입니다.

프로젝트 설치 범위를 선택합니다. 그러면 작업 디렉터리의 .agents 디렉터리에 스킬이 설치됩니다.

마지막으로 Enter를 클릭하여 Yes로 대답하여 설치를 완료합니다. 구성된 스킬이 많은 경우 find-skills 스킬을 설치하려면 예라고 답해도 됩니다.

플러그인으로 서드 파티 스킬 설치

다음으로 obra/superpowers 및 JuliusBrussee/caveman 기술을 설치합니다. 이러한 스킬은 Antigravity CLI 플러그인으로 설치할 수 있으므로 다음 명령어를 사용하여 설치할 수 있습니다.

💻 터미널 셸에서 복사하여 실행

agy plugin install https://github.com/obra/superpowers
agy plugin install https://github.com/JuliusBrussee/caveman

그런 다음 다음 명령어를 사용하여 설치를 확인할 수 있습니다.

💻 터미널 셸에서 복사하여 실행

agy plugin list

다음과 같이 출력됩니다.

{
  "imports": [
    {
      "name": "superpowers",
      "source": "gemini-cli",
      "importedAt": "2026-07-06T01:50:36Z",
      "components": [
        "skills",
        "hooks"
      ]
    },
    {
      "name": "caveman",
      "source": "gemini-cli",
      "importedAt": "2026-07-06T01:50:37Z",
      "components": [
        "skills",
        "agents",
        "commands"
      ]
    }
  ]
}

이로써 스킬 설정이 완료되었습니다. 다음으로 넘어가겠습니다.

7. 맞춤설정 - MCP 도구

MCP (모델 컨텍스트 프로토콜)은 AI 에이전트가 외부 도구를 검색하고 상호작용하는 방식을 표준화하는 개방형 프로토콜입니다. 클라이언트-서버 모델을 정의합니다. 에이전트는 MCP 클라이언트를 호스팅하고 도구는 MCP 서버에 의해 노출됩니다. 모든 MCP 호환 클라이언트는 모든 MCP 호환 서버를 사용할 수 있습니다. 에이전트에는 각 도구에 대한 맞춤 통합 코드가 필요하지 않습니다.

MCP는 클라이언트-서버 아키텍처를 사용합니다.

• 호스트: AI 모델이 있는 애플리케이션 (이 경우 Antigravity CLI)
• 클라이언트: 호스트 내에서 MCP 통신을 처리하는 구성요소 (Antigravity CLI에 내장됨)
• 서버: AI에 기능을 노출하는 경량 프로그램입니다. 이 경우 Google Cloud 관리형 BigQuery MCP 서버를 활용합니다.

이 Codelab의 뒷부분에서 Antigravity CLI가 SDD 워크플로를 실행할 때 테이블 이름, 열 유형, 관계 등 BigQuery 데이터 세트 스키마에 관한 정확한 정보가 필요합니다. BigQuery MCP를 사용하면 Antigravity CLI가 라이브 스키마를 직접 검사할 수 있습니다. 이렇게 하면 환각이 아닌 실제 표와 열을 참조하는 사양과 코드가 생성됩니다.

BigQuery 관리형 MCP 구성

Google은 Google Cloud 인프라에서 관리형 BigQuery MCP 서버를 호스팅합니다. 로컬 설정이 필요하지 않습니다 ( 이 문서에서 지원되는 다른 Google Cloud 제품을 확인할 수 있음). 프로젝트 디렉터리에 MCP 구성 파일을 만들어 Antigravity CLI가 연결되도록 구성합니다.

💻 터미널 셸에서 복사하여 실행합니다.

mkdir -p .agents
cat > .agents/mcp_config.json << EOF
{
  "mcpServers": {
    "bigquery": {
      "serverUrl": "https://bigquery.googleapis.com/mcp",
      "transport": "http",
      "authProviderType": "google_credentials"
    }
  }
}
EOF

이 구성은 AGY에 다음을 알려줍니다.

• BigQuery MCP 서버 (serverUrl)를 찾을 수 있는 위치
• 인증에 Google 사용자 인증 정보 사용 (authProviderType)

구성 파일은 작업공간 수준 (.agents/mcp_config.json)에 있습니다.

Antigravity CLI 내부에서 구성을 확인할 수 있습니다. 먼저 실행해 보겠습니다.

💻 터미널 셸에서 복사하여 실행합니다.

agy

그런 다음 슬래시 명령어 /mcp를 실행하여 구성을 확인합니다.

🤖 Antigravity CLI에서 다음 명령어를 복사하여 실행합니다.

/mcp

다음과 같이 표시됩니다.

그런 다음 Esc를 눌러 슬래시 명령어 상호작용을 종료합니다.

참고: Cloud Shell에서 관리형 BigQuery MCP 서버는 Cloud Shell의 애플리케이션 기본 사용자 인증 정보 (ADC)를 자동으로 사용하므로 추가 OAuth 설정이 필요하지 않습니다. 로컬을 사용하는 경우 gcloud CLI 명령어를 인증하고 다음을 실행해야 합니다.

💻 터미널 셸에서 복사하여 실행

gcloud auth application-default login

Important! BigQuery MCP 서버는 기본적으로 읽기 전용이 아닙니다. 에이전트가 생성하는 모든 SQL을 실행할 수 있으며, 여기에는 파괴적인 문 (DROP, DELETE, TRUNCATE)이 포함됩니다. 이 Codelab에서는 소유하지 않은 공개 데이터 세트를 쿼리하므로 권한으로 인해 파괴적인 작업이 실패합니다. 프로덕션 환경에서 사용하려면 IAM을 사용하여 MCP 도구 사용 제어를 읽고 읽기 전용 액세스를 적용하세요.

지금은 Antigravity CLI를 종료합니다 (Ctrl+D를 두 번 누름).

8. 사양 기반 개발을 사용한 기능 개발

기술/플러그인이 설치되고 BigQuery MCP가 연결되면 이제 사양 기반 개발 워크플로를 사용하여 BigQuery 통합 기능을 공식적으로 지정할 수 있습니다. 이 단계에서 '코딩하기 전에 지정'이 구체화됩니다.

Antigravity CLI를 입력해야 하며, 이 데모에서는 이 플래그를 사용하여 모든 도구 실행을 허용합니다.

💻 터미널 셸에서 복사하여 실행합니다.

agy --dangerously-skip-permissions

중요: 이 플래그는 모든 작업을 허용하므로 위험합니다. 프로덕션 설정에 관한 자세한 내용은 이 문서를 참고하세요. 실습 진행 속도를 높이기 위한 튜토리얼로만 사용됩니다.

원시인 모드 활성화

SDD 주기를 시작하기 전에 동굴인 모드를 활성화하여 다단계 워크플로 전반에서 토큰 사용량을 효율적으로 유지하세요.

🤖 Antigravity에서 다음 명령어를 복사하여 실행합니다.

/caveman:caveman

Antigravity CLI의 대답이 간결해집니다. 추임새와 인사말은 삭제되지만 기술적인 내용은 모두 유지됩니다. 교환당 토큰 수가 적을수록 동일한 할당량 내에서 더 생산적인 대화를 나눌 수 있습니다.

SDD 사양 시작

기능 요청으로 Antigravity CLI를 프롬프트합니다.

🤖 Antigravity에서 다음 명령어를 복사하여 실행합니다.

I want to add a BigQuery integration feature to this e-commerce dashboard app. Currently it reads
from CSV files in the data/ directory. I want to replace the CSV reads with live queries
against the thelook_ecommerce dataset in my BigQuery project using the
google-cloud-bigquery Python client library.

The dashboard should show the same panels (revenue trend, top products, order status,
category performance) but with the full dataset instead of the 500-row CSV subset.

Follow spec-driven-development for development workflow, ensure spec and plan docs created following the superpowers standard in current working directory; also use Bigquery MCP to figure out the data schema.

슈퍼파워 스킬은 기능 수준 요청을 감지하면 자동으로 활성화됩니다. AGY는 코드로 바로 이동하는 대신 SDD 주기를 입력합니다.

중요: AI 에이전트 생성은 동적이며 결과가 서로 다를 수 있습니다.

Antigravity CLI가 현재 프로젝트를 파악하고 필요한 컨텍스트를 수집하는 프로세스를 시작합니다. 아래와 같이 ListDir 및 Read과 같은 명령어가 실행됩니다.

또한 이전에 설정한 BigQuery MCP 연결을 사용하여 데이터 세트의 스키마를 찾습니다.

이렇게 하면 개발을 시작하기 전에 Antigravity CLI에 올바른 컨텍스트가 있는지 확인할 수 있습니다.

요구사항 명확화

Antigravity CLI는 기능 범위에 관해 집중적인 질문을 할 수 있습니다. 일반적인 질문은 다음과 같습니다.

• 프로젝트 ID는 어떻게 구성해야 하나요?
• 수익 추세 차트는 어떻게 집계되고 표시되어야 하나요?
• 통합은 어떻게 접근해야 하나요? 직접 SQL과 로컬 Pandas 비교

상담사의 추천에 따라 이러한 질문에 답변할 수 있습니다.

중요: 프로세스 중간에 Antigravity가 git 작업과 구성을 실행합니다. 이는 --dangerously-skip-permissions 플래그를 사용하기 때문입니다. 이것은 튜토리얼 전용이며 실제 워크플로에서는 직접 처리해야 합니다.

사양 검토

명확히 한 후에는 공식 사양 문서를 생성합니다. 안내를 올바르게 따르면 아래와 같이 docs/superpowers/specs 디렉터리 아래에 사양 문서를 만드는 obra/superpowers 스킬 규칙을 따릅니다.

사양 문서는 다음과 같이 표시됩니다.

# BigQuery Integration Design Specification

## Overview

This document specifies ...

## Architecture

The application currently reads ...

## Data Schema & Sources

All tables reside in the BigQuery ...

...

중요: AI 에이전트 생성은 동적이며 결과가 서로 다를 수 있습니다.

이 내용을 검토한 후 계획 단계로 이동할 수 있도록 사양을 확인해야 합니다.

🤖 Antigravity에서 다음 명령어를 복사하여 실행합니다.

proceed with the specs

계획 단계 및 하위 에이전트 실행

사양을 승인하면 Antigravity CLI가 이를 docs/superpowers/plans 디렉터리에 작성될 구현 계획으로 분해합니다.

계획 문서에는 아래 예와 같은 여러 항목이 나열됩니다.

• 수정할 파일
• 생성/업데이트할 파일
• 종속 항목 변경사항
• 작업 분석

또한 모든 작업을 순차적으로 실행하는 단일 에이전트 대신 Antigravity CLI에서 지원하는 subagent driven development를 사용하는 것이 좋습니다. Antiravity CLI는 전문 하위 에이전트에 작업을 위임할 수 있습니다. 구현 중에 다음과 같은 하위 에이전트가 표시될 수 있습니다.

• 작업 구현자: 계획에 따라 특정 작업의 코드를 작성합니다.
• 작업 검토자: 구현된 코드를 사양에 따라 검토합니다.
• 최종 코드 검토자: 완료 전에 모든 변경사항을 전반적으로 검토합니다.

참고: 여기에서 하위 에이전트를 사용하는 것이 좋습니다. 하위 에이전트는 특정 작업을 격리하고 자체 컨텍스트 윈도우로 오프로드하여 기본 스레드가 실행 출력으로 인해 복잡해지는 것을 방지할 수 있으며 병렬 실행도 허용합니다.

다음과 같은 메시지가 표시되면 다음과 같이 대답하세요.

🤖 Antigravity에서 다음 명령어를 복사하여 실행합니다.

Use subagent driven development

나중에 하위 에이전트가 작업을 하나씩 선택하는 데 위임되는 것을 확인할 수 있습니다.

도움말: 하위 에이전트가 실행되는 동안에도 기본 스레드와 채팅할 수 있습니다. 다음 명령어를 사용하여 활성 상태의 각 하위 에이전트 컨텍스트와 세부정보를 검사할 수 있습니다.

🤖 Antigravity에서 다음 명령어를 복사하여 실행하세요

/agents

도움말: 할당량 문제가 발생한 경우 /usage 명령어로 모델 사용량을 확인하고 /model 명령어로 할당량이 남아 있는 모델로 변경할 수 있습니다 . 그런 다음 continues을 채팅하여 프로세스 계속을 다시 트리거합니다.

이메일을 변경하고 싶으신가요? /logout 명령어를 실행하면 됩니다 . 이렇게 하면 다른 대화 스레드로 이동합니다. 그런 다음 /resume 명령어를 실행하여 이 Codelab 기능 개발에 관한 최근 대화를 찾습니다.

잠시 후 개발이 모두 완료됩니다 ( Final Code Reviewer 에이전트가 생성된 후). 이제 결과를 검사할 수 있습니다.

중요: 원격 저장소에 변경사항을 푸시하라는 메시지가 표시되면 거부하세요.

업데이트된 앱 직접 검토

모든 작업이 완료되면 업데이트된 애플리케이션을 확인할 수 있습니다. Ctrl+D를 두 번 눌러 Antigravity CLI를 종료한 후 다음 명령어를 실행합니다.

💻 터미널 셸에서 복사하여 실행

bash configure_terminal.sh && uv run uvicorn src.main:app --host 0.0.0.0 --port 8080

개발이 성공하면 이제 Total Orders에 120, 000건 이상의 주문이 표시되고 BigQuery와 통합됩니다.

수고하셨습니다 이제 Antigravity CLI의 도움을 받아 BigQuery를 웹 애플리케이션과 성공적으로 통합했습니다.

9. (선택사항) Antigravity CLI로 Cloud Run에 배포

❗ 중요: 이 섹션에서는 활성 Billing 계정이 있는 Cloud 프로젝트가 필요합니다.

대시보드는 Cloud Shell 웹 미리보기를 통해 로컬로 작동합니다. 이 선택사항 단계에서는 공개적으로 액세스할 수 있는 웹 서비스로 Cloud Run에 배포하여 Antigravity CLI의 도메인 기술이 개발에서 운영으로 확장되는 방식을 보여줍니다.

cloud-run-basics 스킬 (앞서 설치한 google/skills 플러그인에서 제공)은 Cloud Run 배포 패턴, Dockerfile 요구사항, 포트 바인딩, gcloud run deploy 플래그에 관한 Antigravity CLI 지식을 제공합니다. 소스 기반 배포 (gcloud run deploy --source .)는 하나의 명령어로 빌드 및 배포합니다. Cloud Build가 컨테이너화를 자동으로 처리합니다.

Cloud Run API 사용 설정

배포에 필요한 API를 사용 설정합니다.

💻 터미널 셸에서 복사하여 실행

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

그런 다음 Antigravity CLI를 입력합니다.

💻 터미널 셸에서 복사하여 실행합니다.

agy --dangerously-skip-permissions

중요: 이 플래그는 모든 작업을 허용하므로 위험합니다. 프로덕션 설정에 관한 자세한 내용은 이 문서를 참고하세요. 실습 진행 속도를 높이기 위한 튜토리얼로만 사용됩니다.

Antigravity CLI에 배포 요청

애플리케이션을 배포하도록 지시해 보겠습니다.

🤖 Antigravity에서 다음 명령어를 복사하여 실행합니다.

Deploy this application to Cloud Run, name the service "bigquery-dashboard" and make it publicly accessible

cloud-run-basics 스킬을 읽어 현재 프로젝트 웹 애플리케이션을 배포하기 위한 요구사항을 파악합니다.

완료되면 배포가 성공했는지 확인하고 아래 예와 같이 이전에 실행된 배포 프로세스의 요약을 제공합니다. 제공된 URL로 애플리케이션에 액세스할 수 있습니다.

이제 Antigravity CLI를 사용하여 라이브 애플리케이션을 완전히 배포하고 액세스할 수 있습니다.

10. 결론

애플리케이션 코드를 직접 작성하지 않고도 정적 CSV 파일에서 실시간 BigQuery 데이터로 이커머스 대시보드를 업그레이드했습니다. Antigravity CLI는 재사용 가능한 기술과 MCP를 통한 데이터의 실시간 연결을 기반으로 하는 규율 있는 사양 기반 개발 워크플로를 통해 구현을 처리했습니다.

학습한 내용

• AI 지원 개발을 위해 Cloud Shell에서 Antigravity CLI를 사용하는 방법
• 에이전트 기술이란 무엇이며, 점진적 공개가 컨텍스트 윈도우를 효율적으로 유지하는 방법
• 세 가지 기술 카테고리: 방법론 (초능력), 효율성 (원시인), 도메인 지식 (google/skills)
• MCP란 무엇이며 실시간 데이터 액세스를 위해 BigQuery MCP를 구성하는 방법
• 바이브 코딩 대신 사양 기반 개발 주기 (지정 → 계획 → 구현)를 실행하는 방법
• Antigravity CLI가 하위 에이전트를 생성하여 개발을 더 집중적이고 효율적으로 만드는 방법

정리

이 Codelab에서 생성된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 개별 리소스를 삭제하거나 전체 프로젝트를 삭제하면 됩니다.

옵션 1: 프로젝트 삭제 (권장)

정리하는 가장 쉬운 방법은 프로젝트를 삭제하는 것입니다. 이렇게 하면 프로젝트와 연결된 모든 리소스가 삭제됩니다.

💻 터미널 셸에서 복사하여 실행합니다.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

중요: 이 명령어 gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}를 사용하면 제한된 기간 동안 이 삭제 작업을 실행취소할 수 있습니다.

옵션 2: 개별 리소스 삭제

프로젝트는 유지하고 이 Codelab에서 만든 리소스만 삭제하려면 다음 단계를 따르세요.

💻 터미널 셸에서 복사하여 실행합니다.

bq rm -r -f $GOOGLE_CLOUD_PROJECT:thelook_ecommerce
gcloud run services delete bigquery-dashboard --region us-central1 --quiet