Antigravity 및 Spec-kit을 사용한 사양 기반 ADK 에이전트 개발

1. 소개

기존 에이전트에 기능(새 데이터베이스 지원 기능)을 추가하려면 일반적으로 상용구를 작성하고, 통합을 연결하고, 코드베이스에 이미 있는 패턴과 모든 항목을 일관되게 유지해야 합니다. Antigravity는 이 프로세스의 모든 단계를 가속화합니다. 코드베이스를 분석하여 필요한 컨텍스트를 빌드하고, 검토를 위해 구조화된 사양과 구현 계획을 생성하고, 코드 변경사항을 실행합니다. 이 모든 과정은 재사용 가능한 기술과 협상 불가능한 원칙을 적용하는 프로젝트 헌장으로 포착하는 데 도움이 되는 도메인 지식에 따라 진행됩니다. 이 Codelab에서는 spec-kit을 많이 참조하는 사양 문서를 강화하는 새로운 주기를 도입하여 Antigravity Spec-driven Development 패러다임을 강화하는 방법을 소개합니다.

빌드할 항목

완전한 SDD 주기를 통해 예약이 추가된 로컬에서 실행되는 레스토랑 컨시어지 애플리케이션:

• 예약 - 게스트가 테이블을 예약하고 예약을 확인합니다. 새로운 MCP 도구 상자 데이터베이스 도구와 Cloud SQL reservations 테이블이 지원됩니다.
• (챌린지) – 에이전트용 UI 직접 개발
• (챌린지) – Antigravity 에이전트의 도움을 받아 Google Cloud에 배포

시작 코드는 메뉴 검색 (MCP 도구 상자를 통한 키워드 + 시맨틱) 및 식단 선호도 추적 (ToolContext를 통해)이 포함된 작동하는 ADK 에이전트를 제공합니다. 애플리케이션 코드를 직접 작성하지 않고도 확장할 수 있습니다. Antigravity는 사양에 따라 구현을 처리합니다.

학습할 내용

• Antigravity가 기존 코드베이스를 이해할 수 있도록 프로젝트 컨텍스트를 부트스트랩하는 방법
• 도메인 지식을 패키징하는 Antigravity 스킬을 만드는 방법 (예: ADK Codelab 패턴)을 재사용할 수 있습니다.
• 계획 및 분석 중에 SDD 워크플로에서 검증하는 프로젝트 헌장을 설정하는 방법
• Antigravity에서 사양 기반 개발 (SDD) 워크플로를 사용하여 체계적으로 기능을 추가하는 방법
• MCP 도구 상자를 통해 새로운 데이터베이스 지원 도구로 ADK 에이전트를 확장하는 방법

기본 요건

• 로컬 머신에 설치된 Google Antigravity 및 git
• 무료 체험 결제 계정이 사용 설정된 Google Cloud 계정
• 이전의 필수 ADK Codelab 4개 완료 (또는 이에 상응하는 지식)는 사용 사례 컨텍스트를 이해하는 데 도움이 됩니다.
• ADK를 사용한 AI 에이전트 빌드: 기초
• ADK를 사용한 AI 에이전트 빌드: 도구로 지원
• ADK 및 CloudSQL을 사용한 지속적인 AI 에이전트 빌드
• Cloud Run에서 ADK 에이전트 배포, 관리, 관찰
• 도구로서의 데이터베이스: ADK, MCP 도구 상자, Cloud SQL을 사용한 에이전트형 RAG

2. 환경 설정

중요사항:

이 튜토리얼을 진행하려면 활성 결제 계정이 있는 Google Cloud 프로젝트가 필요합니다. 아직 계정이 없는 경우 아래 단계에 따라 이 튜토리얼에 사용할 수 있는 무료 체험 결제 계정을 받으세요.

1. 시크릿 창 열기
2. 워크숍 세션에 참여하는 경우 일반적으로 세션에서 사용 포털 URL이 제공됩니다. 그렇지 않은 경우 이 무료 체험 결제 계정 사용 포털로 이동하세요.
3. 개인 Gmail 계정으로 로그인합니다. ( Google Workspace / 기타 이메일은 작동하지 않습니다. )
4. 단계별 사용 안내를 따르세요.

이 단계에서는 시작 저장소를 클론하고, Google Cloud로 인증하고, Cloud SQL 데이터베이스를 프로비저닝하고, 로컬 Antigravity 환경을 준비합니다.

참고: 이 Codelab은 로컬 머신의 Google Antigravity에서 완전히 실행됩니다. 설정에는 gcloud CLI 명령어를 사용한 수동 인증이 포함됩니다.

시작 저장소 클론

Antigravity (또는 시스템 터미널)에서 터미널을 엽니다. 동반 저장소를 클론하고 디렉터리를 입력합니다.

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

Antigravity에서 클론된 저장소를 엽니다. 파일->폴더 열기->복제된 디렉터리 sdd-adk-agents-agy 선택

업스트림 리모컨을 삭제합니다. SDD 워크플로는 기능 사양의 git 브랜치를 만듭니다. 원격 저장소를 삭제하면 실수로 스타터 저장소에 푸시하는 것을 방지할 수 있습니다.

git remote remove origin

중요: 이 Codelab의 SDD 워크플로는 git 브랜치를 사용하여 기능 사양을 정리합니다. origin 원격을 삭제하면 로컬 브랜치와 커밋이 로컬에 유지됩니다. 작업을 백업하려면 자체 원격을 추가하세요. git remote add origin <your-repo-url>

기본 요건 설치

기본 요건 스크립트를 실행합니다. git, curl, gcloud, uv, Python 3.12, MCP Toolbox를 확인하고 누락된 경우 설치합니다.

bash scripts/setup_prerequisites.sh

참고: 모든 필수 구성요소를 다운로드하는 데 시간이 걸리므로 다운로드가 완료되는 동안 새 탭을 열어 다음 섹션으로 계속 진행하세요.

Google Cloud로 인증

인증 명령어 두 개를 실행합니다. 둘 다 OAuth용 브라우저를 엽니다.

gcloud auth login
gcloud auth application-default login

참고: 두 번째 OAuth 명령어에서 권한을 선택하라는 메시지가 표시될 때 모든 옵션 확인

참고: 무료 체험 결제 계정을 신청할 때 사용하는 이메일로 인증해야 합니다.

Antigravity를 사용하여 로컬로 작업하므로 수동으로 인증합니다. auth login는 gcloud CLI를 인증합니다. application-default login는 애플리케이션에서 사용하는 Google Cloud SDK를 인증합니다. ADK의 Vertex AI 호출과 Cloud SQL Python 커넥터는 모두 애플리케이션 기본 사용자 인증 정보를 사용합니다.

Google Cloud 프로젝트 설정

프로젝트 설정 스크립트를 실행하기 전에 위치 변수를 .env에 씁니다.

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global는 Vertex AI / Gemini API 호출에 사용됩니다.
• REGION=us-central1은 Cloud SQL 및 기타 GCP 인프라에 사용됩니다.

프로젝트 설정 스크립트를 다운로드하여 실행합니다. 무료 체험 결제로 Google Cloud 프로젝트를 만들거나 검증하고 프로젝트 ID를 .env에 저장한 후 소싱합니다.

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

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

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

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

Cloud SQL 프로비저닝

데이터베이스 비밀번호를 설정하고 .env에 추가합니다.

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

중요: 위의 하드코딩된 비밀번호는 튜토리얼 목적으로만 사용됩니다. 프로덕션 환경에서는 Secret Manager와 같은 서비스를 사용하여 사용자 인증 정보를 안전하게 저장하고 런타임에 참조하세요. 일반 텍스트 보안 비밀을 소스 제어에 커밋하지 마세요.

Cloud SQL 인스턴스를 만듭니다.

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

db-custom-1-3840 등급은 Vertex AI ML 통합에 필요한 최소 등급입니다. --enable-google-ml-integration 플래그를 사용하면 Cloud SQL이 SQL에서 Gemini 임베딩 모델을 직접 호출할 수 있으며, 이는 시맨틱 검색 기능을 지원합니다.

참고: 이 명령어는 약 5분 정도 걸리며 백그라운드에서 실행됩니다. 이 터미널 탭에서 실행 중인 상태로 두고 다음 단계를 위해 새 터미널 탭을 엽니다.

종속 항목 설치

새 터미널 탭을 엽니다. 클론된 저장소 프로젝트 디렉터리에 있는지 확인하고 환경 변수를 다시 로드합니다.

source .env

uv를 Python 프로젝트 관리자로 사용합니다. uv은 Rust로 작성된 빠른 Python 패키지 및 프로젝트 관리자입니다 ( 문서). 이 Codelab에서는 속도와 단순성을 위해 이를 사용합니다. Python 종속 항목을 설치합니다.

uv sync

그런 다음 프로젝트 구성으로 ADK 에이전트의 .env 파일을 업데이트합니다.

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

이제 작업에 필요한 모든 필수 스타터 ADK 에이전트 저장소가 있어야 합니다. 이제 모든 것이 준비되는 동안 다음 섹션에서 Antigravity와 사양 기반 개발에 대해 자세히 알아보겠습니다.

3. 시작 코드 살펴보고 사양 기반 개발 이해하기

이 단계에서는 시작 코드 구조를 살펴보고, 사양 기반 개발 방법론을 소개하고, 데이터베이스를 시드하고, 확장하기 전에 기본 에이전트가 작동하는지 확인합니다.

프로젝트 구조

클론된 저장소 프로젝트를 Antigravity 편집기에서 열고 디렉터리 레이아웃을 검토합니다.

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

키 파일

에이전트 애플리케이션 파일

• restaurant_concierge/agent.py - 핵심 에이전트입니다. MCP 도구 상자 데이터베이스 도구와 ToolContext 기반 식단 선호도 추적을 결합한 LlmAgent 에이전트는 도구 상자 서버에서 모든 도구를 로드하고 ToolContext를 사용하여 상태를 관리하는 두 개의 Python 함수 (save_dietary_preference, get_dietary_preferences)를 추가합니다.
• tools.yaml - MCP Toolbox 도구 정의입니다. 키워드 검색 (search_menu), pgvector을 통한 시맨틱 검색 (semantic_search_menu), 카테고리 필터 (get_menu_by_category)의 세 가지 메뉴 검색 도구가 정의되어 있습니다. 아직 예약 도구는 없으며 나중에 추가합니다.
• server.py - FastAPI 객체로 ADK에 액세스하는 방법을 보여주는 최소한의 FastAPI 서버입니다. ADK의 get_fast_api_app()는 SSE 스트리밍 및 세션 관리 API를 위한 /run_sse를 비롯한 내장 엔드포인트를 제공합니다.

Antigravity 파일

• .agents/skills/adk-agent-development/SKILL.md - 4개의 ADK Codelab에서 가져온 간결한 참조 패턴이 포함된 사전 구성된 스킬 ( Antigravity에서 생성)입니다. 현재 비활성 상태입니다 (YAML 프런트매터 누락). 나중에 업데이트해야 합니다. Antigravity는 ADK 에이전트 기능 및 그 예와 관련된 작업을 감지하면 이 스킬을 자동으로 로드합니다. 이는 나중에 Antigravity가 예약 기능을 계획할 때 안내하는 지식입니다.
• .agents/skills/repo-research/SKILL.md - Antigravity에 저장소를 점진적으로 분석하고 구조화된 프로젝트 컨텍스트 문서를 생성하는 방법을 알려주는 스킬입니다. 4단계 접근 방식을 사용합니다. 표면 스캔 (디렉터리 트리만), 구성 및 메타데이터 파일, 진입점 및 데이터 모델, 타겟팅된 심층 분석이 있으며 각 단계는 다음 단계로 진행하기 전에 중지하고 발견 항목을 작성합니다. ADK 스킬과 마찬가지로 나중에 YAML 프런트매터를 추가할 때까지는 비활성 상태입니다. 활성화되면 이를 호출하여 아키텍처, 런타임 종속 항목, API 노출 영역, 도메인 용어집을 다루는 포괄적인 온보딩 문서인 .agents/rules/project-context.md를 생성합니다.

사양 기반 개발: Antigravity의 내장 계획부터 구조화된 SDD까지

AI 코딩 어시스턴트를 사용하면 프롬프트에서 코드를 쉽게 생성할 수 있습니다. 위험: 기능을 한 문장으로 설명하면 어시스턴트가 수백 줄을 작성하고, 보기에 적절해 보여서 이를 수락합니다. 이를 '바이브 코딩'이라고도 합니다. 감각에 따라 방향을 정하고, 작동하는지 여부에 따라 출력을 수락하거나 거부합니다. 프로토타입과 일회성 스크립트에 적합합니다. 코드베이스가 커지거나, 기능이 상호작용하거나, 몇 주 후에 코드를 다시 방문하여 결정을 내린 이유를 재구성할 수 없는 경우 문제가 발생합니다.

사양 기반 개발 (SDD)은 이 루프에 구조를 추가합니다. 코드를 생성하기 전에 기능이 하는 일, 기능이 제공하는 대상, 성공 기준을 명시하는 사양을 작성합니다. AI 어시스턴트는 이 사양을 기반으로 작동하며, 출력을 검토할 때도 마찬가지입니다. 사양이 의도의 단일 정보 소스가 됩니다. 코드가 사양과 다른 경우 검토에서 이를 포착합니다. 요구사항이 변경되면 먼저 사양을 업데이트한 다음 재생성합니다. 결정은 즉흥적으로 이루어지는 것이 아니라 문서화됩니다.

트레이드오프는 실제입니다. SDD는 바이브 코딩보다 기능당 속도가 느립니다. 코드를 작성하기 전에 문서를 작성합니다. 하지만 그 보상은 복리로 늘어납니다. 향후 코드베이스에 대한 모든 변경사항에는 컨텍스트가 있고, 모든 AI 생성 구현에는 검토 가능한 계약이 있으며, 기억에 의존하여 결정을 설명하는 대신 사양을 가리켜 공동작업자 (사람 또는 AI)를 온보딩할 수 있습니다.

Antigravity는 이미 사양 기반 개발 원칙을 따르고 있습니다. 에이전트를 계획 모드로 설정하면 코드를 작성하기 전에 두 가지 아티팩트가 생성됩니다.

• 구현 계획 - 제안된 기술적 접근 방식, 파일 변경사항, 아키텍처 결정에 대한 개요
• 할 일 목록: 작업 항목의 구조화된 분류

Antigravity는 실행 전에 이러한 아티팩트를 검토하고 승인하도록 요청합니다. 이 계획 후 구현 루프는 사양 기반 개발의 핵심입니다. 사양이 코드를 안내하며 그 반대는 아닙니다.

이 Codelab에서는 GitHub의 사양 기반 개발 프레임워크인 spec-kit을 기반으로 하는 주관적인 버전 관리 워크플로를 사용하여 이 기반을 확장합니다. 모든 기능은 각 아티팩트가 git에서 검토, 수정, 추적할 수 있는 독립형 문서인 의도적인 파이프라인을 거칩니다. 파이프라인에는 문제가 구현 문제로 발전하기 전에 문제를 포착하는 두 가지 선택적 품질 게이트 단계 (명확화 및 분석)가 포함됩니다.

단계	아티팩트	목적
/speckit.specify	spec.md	빌드할 항목 정의 (사용자 대상, 기술에 구애받지 않음)
/speckit.clarify (선택사항)	spec.md에 업데이트됨	명세가 부족한 영역을 파악하고, 구체적인 질문을 하고, 답변을 명세에 다시 인코딩
/speckit.plan	plan.md, data-model.md, research.md	빌드 방법 설계 (기술적 접근 방식, 데이터 모델, 연구)
/speckit.tasks	tasks.md	계획을 순서가 지정된 실행 가능한 단계로 나누기
/speckit.analyze (선택사항)	분석 보고서	구현 전에 위험, 격차 또는 누락된 극단적인 사례가 있는지 작업을 검토하세요.
/speckit.implement	코드 변경	각 작업을 확인하면서 작업을 실행합니다.

모든 아티팩트는 specs/<feature-branch>/에 파일로 유지되고, git에서 버전 제어되며, 재사용 가능합니다. 대화가 중단되거나 나중에 결정을 다시 검토하고 싶을 때 사양 문서는 항상 채팅 기록에 묻혀 있지 않고 바로 확인할 수 있습니다.

참고: Antigravity 내장 아티팩트는 UI에서 우위를 점하고 있어 사용자가 생성된 아티팩트 ( 이미지 포함)에 댓글을 달 수 있습니다. 따라서 이 튜토리얼에서는 implement 단계에서 기본 제공 아티팩트와 통합되도록 원래 spec-kit 프롬프트를 수정합니다.

스타터 저장소에는 .agents/workflows/의 이러한 SDD 워크플로와 .specify/templates/의 템플릿이 포함됩니다. 나중에 이를 사용하여 에이전트에 기능을 추가합니다.

4. Cloud SQL 설정 완료 및 기본 에이전트 기능 보장

Cloud SQL 생성 명령어가 실행 중인 터미널 탭으로 다시 전환합니다. 완료되면 인스턴스가 준비되었는지 확인합니다.

gcloud sql instances describe restaurant-db --format="value(state)"

출력에 RUNNABLE이 표시되면 계속 진행합니다. PENDING_CREATE이 표시되면 잠시 기다렸다가 명령어를 다시 실행합니다.

Cloud SQL 서비스 계정에 Vertex AI 액세스 권한을 부여합니다 (데이터베이스 내 삽입 함수에 필요).

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

데이터베이스를 만듭니다.

gcloud sql databases create restaurant_db --instance=restaurant-db

다음과 같은 출력이 표시됩니다.

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

체크포인트: .env 파일에 GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION, DB_PASSWORD이 포함되어 있습니다. Cloud SQL 인스턴스 restaurant-db이 실행 중입니다. toolbox이 PATH에 있습니다 (setup_prerequisites.sh에 의해 설치됨). Python 종속 항목이 설치되어 있습니다.

데이터베이스 시드

환경 변수를 로드하고 데이터베이스 시드 스크립트를 실행하여 스키마를 만들고 메뉴 항목 16개를 삽입합니다.

source .env
uv run python scripts/seed_db.py

예상 출력:

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

시맨틱 검색을 위한 벡터 임베딩을 생성합니다.

uv run python scripts/generate_embeddings.py

예상 출력:

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

여기서는 Cloud SQL의 기본 제공 embedding() 함수 (google_ml_integration 확장 프로그램을 통해)를 사용하여 SQL에서 직접 gemini-embedding-001를 호출합니다. 3072차원 벡터는 menu_items의 embedding 열에 저장되므로 애플리케이션 측 삽입 코드가 필요하지 않습니다.

기본 에이전트 테스트

MCP 도구 상자를 백그라운드 프로세스로 시작합니다.

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

툴박스는 HTTP를 통해 데이터베이스 도구를 제공합니다. 상담사는 http://127.0.0.1:5000에서 연결됩니다.

ADK 개발 UI를 시작합니다.

uv run adk web .

브라우저에서 개발 UI를 엽니다. 그런 다음 다음 프롬프트로 에이전트를 테스트합니다.

What appetizers do you have?

검사: 에이전트가 데이터베이스를 쿼리하고 메뉴 항목을 반환합니다.

I'm vegetarian

검사: 에이전트가 에이전트 상태에 식단 선호도를 저장합니다.

Can I make a reservation for tomorrow?

검사: 에이전트가 이 문제를 처리할 수 없습니다 (아직 예약 도구가 없음).

Ctrl+C를 두 번 사용하여 ADK 개발 UI를 중지합니다. 나중에 다시 사용하므로 도구 상자를 백그라운드에서 실행 상태로 둡니다.

체크포인트: 기본 에이전트가 작동합니다. 메뉴 검색 (키워드 + 시맨틱) 및 식단 선호도 기능이 올바르게 작동합니다. 예약 도구가 없기 때문에 예약 요청이 실패합니다. 프로젝트 구조와 해결해야 할 격차를 이해합니다.

5. Antigravity로 프로젝트 컨텍스트 부트스트랩

이제 일상적인 작업에 '약간 더 가까운' 조건으로 시뮬레이션해 보겠습니다.

• 저장소가 제대로 관리되지 않음
• 리드미가 오래됨
• 문서가 자주 업데이트되지 않음

참고: 이 내용이 내 상태를 반영하지 않는다면 매우 운이 좋은 것입니다.

이러한 상황에서 가장 먼저 해야 할 일은 일반적으로 Antigravity가 작업할 프로젝트에 관한 지도나 컨텍스트를 만드는 것입니다. 이 단계에서는 저장소를 분석하고 프로젝트 컨텍스트 문서를 생성하는 스킬을 만들어 Antigravity에 기존 코드베이스를 깊이 이해시키는 방법의 한 가지 접근 방식을 보여줍니다.

또한 SDD 워크플로에서 검증하는 협상 불가능한 원칙인 프로젝트 헌법을 설정합니다. 이러한 요소는 나중에 SDD 주기에 필요한 컨텍스트와 제약 조건을 Antigravity에 제공합니다.

Antigravity 컨텍스트 계층 구조

Antigravity는 각각 범위가 다른 세 가지 수준의 컨텍스트를 사용합니다.

• 규칙 (.agents/rules/): 항상 활성 상태인 요청 사항입니다. 이 워크스페이스의 모든 대화에 표시됩니다 ( 활성화한 경우). 아키텍처 결정, 코딩 표준, 기술 스택 정보와 같은 프로젝트 전반의 컨텍스트에 규칙을 사용하세요.
• 기술 (.agents/skills/): 주문형 지식입니다. Antigravity는 현재 작업이 스킬의 description 필드와 일치하는 경우에만 스킬을 로드합니다. 도메인별 참조 자료에 스킬을 사용하세요.
• Workflows (.agents/workflows/): / 명령어로 트리거되는 저장된 프롬프트입니다. SDD 파이프라인과 같은 반복 가능한 다단계 프로세스에 워크플로를 사용합니다.

참고: 현재 프로젝트에는 워크플로 (SDD 파이프라인)와 스킬 (ADK 에이전트 개발)이 있지만 규칙은 없습니다. project-context.md 규칙은 사용 중인 기술, 파일 구성 방식, 지금까지 빌드된 항목 등 코드베이스에 대한 지속적인 이해를 Antigravity에 제공합니다.

스킬 활성화

시작 저장소에는 .agents/skills/에 미리 작성된 두 가지 스킬이 포함되어 있습니다. 자세한 안내가 포함되어 있지만 필수 YAML 프런트매터 대신 TODO(codelab) 주석으로 시작합니다. 프런트매터가 없으면 Antigravity에서 이를 검색할 수 없습니다.

무중력 기술에는 파일 상단에 두 필드가 있는 YAML 프런트매터 블록이 필요합니다.

• name - 스킬의 고유 식별자
• description: 특정 요청에 로드할 스킬을 결정할 때 Antigravity가 일치시키는 자연어 요약

영업 중

.agents/skills/adk-agent-development/SKILL.md

편집기에서 상단의 두 TODO(codelab) 주석 줄을 다음 프런트매터로 바꿉니다.

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

참고: ADK 에이전트 개발 스킬에는 5개의 ADK Codelab(에이전트 구조, 도구 유형, 상태 관리, 배포

영업 중

.agents/skills/repo-research/SKILL.md

편집기에서 상단의 두 TODO(codelab) 주석 줄을 다음 프런트매터로 바꿉니다.

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

참고: repo-research SKILL.md를 자세히 읽어보세요. 다음은 저장소를 분석하는 프롬프트의 예입니다. 증분 업데이트 규칙은 의도적으로 보수적입니다. 조사 중에 Antigravity의 컨텍스트가 소진되거나 대화가 중단되면 지금까지 발견된 모든 항목이 파일에 이미 저장됩니다. 스킬을 다시 호출하면 진행 상황이 손실되지 않고 중단된 지점부터 다시 시작됩니다.

경고! 큰 저장소를 분석하면 할당량이 빠르게 소진될 수 있습니다.

두 스킬 모두 유효한 프런트매터가 있는지 확인합니다.

head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

각각 name: 및 description: 필드를 래핑하는 --- 구분 기호가 표시되어야 합니다. 구분자나 필드가 누락되면 Antigravity에서 스킬을 인식하지 못합니다.

두 스킬 모두 주문형으로 로드됩니다. Antigravity는 description 필드에 대해 요청을 일치시키고 관련성이 있는 경우에만 전체 안내를 가져옵니다.

프로젝트 컨텍스트 생성

규칙 디렉터리가 있는지 확인합니다.

mkdir -p .agents/rules

Antigravity의 에이전트 관리자/채팅 상자 (편집기 모드에서 ctrl + L 누름)에서 새 대화를 시작합니다. 유형:

Research this repository and create a project context document

Antigravity는 요청을 repo-research 기술과 일치시키고 코드베이스를 체계적으로 분석하기 시작합니다. 구성 파일, 소스 코드, 문서를 읽은 다음 발견한 내용을 프로젝트 컨텍스트 템플릿에 채웁니다.

완료되면 편집기에서 .agents/rules/project-context.md을 엽니다. 여기에는 기술 스택 (Python 3.12, ADK, MCP Toolbox, Cloud SQL), 프로젝트 구조, 데이터 모델 (pgvector가 있는 menu_items 테이블), 외부 통합 등 프로젝트에 관한 구체적인 정보가 포함되어 있습니다.

도움말: 프로젝트가 진행됨에 따라 프로젝트 컨텍스트 문서가 늘어납니다. 스킬을 다시 실행하여 새로운 추가 항목으로 컨텍스트를 업데이트할 수 있습니다. 증분 업데이트 규칙은 기존 콘텐츠가 유지되도록 합니다. 새 기술, 항목, 통합은 덮어쓰지 않고 추가됩니다.

타겟팅된 업데이트의 경우 '데이터베이스 스키마를 조사하고 프로젝트 컨텍스트를 업데이트해' 또는 '새 도구 정의로 프로젝트 컨텍스트를 업데이트해'와 같은 구체적인 프롬프트를 사용하세요. 각 호출은 기존 문서에 추가됩니다.

프로젝트 헌법 설정

SDD 워크플로는 계획 및 분석 중에 .specify/memory/constitution.md에서 프로젝트 헌법을 참조합니다. /speckit.plan 워크플로는 이에 대해 '헌법 확인'을 실행하고 /speckit.analyze는 위반을 심각으로 표시합니다. 헌법이 자리표시자 토큰이 포함된 빈 템플릿으로 남아 있으면 이러한 검사에서 검증할 대상이 없으므로 계획과 분석이 가이드라인 없이 실행됩니다.

헌법은 협상할 수 없는 프로젝트 원칙을 정의합니다. 이 저장소는 단일 개발자가 유지관리하는 작은 저장소이므로 헌법은 이러한 범위를 반영해야 합니다. 간단하고 일관되게 유지하고 과도한 엔지니어링을 피하세요.

Antigravity의 Agent Manager에서 새 대화를 시작합니다. 헌법 워크플로를 실행합니다.

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

Antigravity는 구체적인 원칙으로 헌법 템플릿을 채우고 버전을 할당 (1.0.0)하고 SDD 템플릿 전반에서 일관성 검사를 실행합니다.

.specify/memory/constitution.md에서 생성된 헌법을 검토합니다. 세 가지 원칙이 존재하고 명확하게 명시되어 있는지 확인합니다.

참고: 헌법은 솔로 개발자를 위한 3가지 원칙으로 의도적으로 유지됩니다. /speckit.constitution 워크플로는 증분 수정사항을 지원합니다. 추가 원칙을 사용하여 다시 실행하면 버전 관리가 자동으로 처리됩니다. 팀 프로젝트의 경우 코드 검토, 테스트 규율, 관측 가능성, API 버전 관리에 관한 원칙을 추가합니다.

체크포인트: .agents/rules/project-context.md에 저장소에 관한 구체적인 정보가 있습니다. .agents/skills/repo-research/SKILL.md은 YAML 프런트매터, 안내, 충돌 해결을 사용한 스킬 생성을 보여줍니다. .specify/memory/constitution.md에는 계획 및 분석 워크플로에서 검증하는 세 가지 프로젝트 원칙이 포함되어 있습니다. 3단계 컨텍스트 계층 구조(규칙(항상 활성), 스킬(온디맨드), 워크플로(슬래시 명령어))를 이해합니다.

6. SDD 주기 - 예약 추가 기능

이 단계에서는 레스토랑 컨시어지 에이전트에 예약 예약을 추가하기 위해 전체 SDD 주기를 살펴봅니다. 각 단계(지정, 명확화, 계획, 작업, 분석, 구현)를 통해 Antigravity를 진행하면서 각 아티팩트가 이전 아티팩트를 기반으로 어떻게 빌드되는지 관찰합니다. 이 부분이 Codelab의 핵심 학습 경험입니다.

중요: Antigravity는 AI 어시스턴트이므로 생성된 아티팩트 (사양, 계획, 작업, 코드)가 이 튜토리얼에 설명된 내용과 다를 수 있습니다. 파일 이름, 정확한 SQL 스키마, 코드 구조는 다를 수 있습니다. 이는 예상된 동작이며 AI 지원 개발을 사용하는 과정의 일부입니다. SDD 워크플로를 사용하면 모든 아티팩트가 코드가 되기 전에 검토할 수 있으므로, 기대치와 일치하지 않는 출력을 판단에 따라 수락, 수정 또는 재생성하세요.

기능 지정

Antigravity의 Agent Manager에서 새 대화를 시작합니다. 기능 설명과 함께 /speckit.specify 워크플로 명령어를 입력합니다.

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

Antigravity는 기능 브랜치를 만들고 사양 문서를 생성하며 품질 유효성 검사를 실행합니다. Antigravity에서 설명이 필요한 질문을 제시하는 경우 위의 기능 설명을 기반으로 답변하세요.

참고: 사양을 완료하면 Antigravity에서 '기술 계획 수립' 또는 '사양 요구사항 명확히 하기'와 같은 핸드오프를 표시할 수 있습니다. 다음 워크플로 단계 (/speckit.plan 또는 /speckit.clarify)로의 신호입니다.

사양은 '어떻게'가 아닌 '무엇'과 '왜'에 초점을 맞춥니다. SQL 테이블, tools.yaml 또는 ADK API를 언급하지 않고 사용자 환경 ('게스트는 이름, 파티 규모, 날짜, 시간을 입력하여 예약할 수 있습니다')을 설명합니다. 구현 세부정보는 계획 단계에서 제공됩니다.

specs/<branch-name>/spec.md에서 생성된 사양을 검토합니다. 기능 요구사항과 성공 기준을 포착하는지 확인합니다.

사양 명확히 하기 (선택사항)

명확히 하기 워크플로를 실행하여 사양에서 명시되지 않은 영역을 식별하고 해결합니다.

/speckit.clarify

Antigravity는 사양에서 모호한 부분, 누락된 수락 기준, 구체적으로 명시되지 않은 요구사항을 검사합니다. 짧은 선택이나 문구로 답할 수 있는 타겟팅된 명확성 질문을 합니다. 답변은 사양에 직접 다시 인코딩되므로 계획을 시작하기 전에 더 정확해집니다.

도움말: 명확히 하기 단계는 선택사항이지만 복잡한 기능에는 권장됩니다. 간단한 사양의 경우 계획으로 바로 건너뛰세요.

구현 계획

계획 워크플로를 실행합니다.

/speckit.plan

Antigravity는 다음 두 단계를 통해 기술 계획을 생성합니다.

1. 조사 단계: 기존 코드베이스에 관한 미지의 요소를 해결하고 research.md를 생성합니다.
2. 설계 단계 - data-model.md (예약 항목 정의)를 생성하고 project-context.md를 업데이트합니다.

Antigravity는 계획 중에 adk-agent-development 스킬을 사용해야 합니다. 주요 아티팩트를 검토합니다.

• specs/<branch-name>/plan.md - 기술적 접근 방식: 수정할 파일, 따라야 할 패턴
• specs/<branch-name>/data-model.md - 예약 항목 정의 (열, 유형, 관계)
• specs/<branch-name>/research.md - 결정 및 근거

작업 생성

태스크 워크플로 실행

/speckit.tasks

Antigravity는 계획을 specs/<branch-name>/tasks.md의 순서가 지정된 작업 목록으로 나눕니다. 작업은 ID, 우선순위 마커, 파일 경로가 포함된 엄격한 체크리스트 형식을 따릅니다. 예를 들면 다음과 같습니다.

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

작업은 설정 → 기본 → 사용자 스토리 → 다듬기 단계로 구성됩니다. 할 일 목록을 검사하여 생성되고 수정될 항목을 파악합니다.

작업 분석 (선택사항)

분석 워크플로를 실행하여 위험과 격차에 대한 작업을 검토합니다.

/speckit.analyze

Antigravity는 사양 및 계획에 대해 작업 목록을 확인하여 누락된 특이 사례, 충돌할 수 있는 작업 또는 사양의 요구사항과 계획된 작업 간의 격차를 찾습니다. 구현하기 전에 심각한 문제를 해결하세요.

도움말: 분석 단계는 작업 목록이 길거나 기능이 여러 하위 시스템에 영향을 미치는 경우에 가장 유용합니다. 예약과 같은 집중된 기능의 경우 간단한 스캔으로 충분합니다.

7. 구현

구현 워크플로를 실행합니다.

/speckit.implement

Antigravity는 최종 구현 계획과 작업 아티팩트를 제시합니다. 검토하고 승인하여 계속 진행하세요.

도움말: 바로 댓글을 달 수 있습니다. 이는 Antigravity 내장 아티팩트로만 실행할 수 있습니다.

Antigravity는 작업을 실행하고 완료될 때마다 각 작업을 확인합니다. 완료되면 전체 둘러보기가 표시됩니다.

코드 변경사항 테스트

구현이 완료되면 주요 변경사항이 적용되었는지 확인합니다. 정확한 파일 이름과 콘텐츠는 다를 수 있지만 이러한 패턴은 tools.yaml 및 agent.py과 같이 있어야 합니다.

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

다음과 같은 출력이 표시됩니다.

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

agent.py의 경우

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

다음과 같은 변경사항이 있을 수 있습니다.

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

참고: grep에서 두 파일 모두에 일치하는 항목이 반환되지 않으면 구현에서 다른 이름을 사용했을 수 있습니다. git diff를 확인하여 전체 변경사항을 확인하고 예약 관련 로직이 추가되었는지 확인합니다.

변경사항이 시드 데이터베이스 스크립트에 영향을 미쳐야 합니다. 실행해 보겠습니다.

source .env
uv run python scripts/seed_db.py

업데이트된 스크립트는 reservations 테이블이 아직 없으면 이 테이블을 만들어야 합니다. 새 테이블이 생성되었음을 확인하는 출력이 표시됩니다 (기존 menu_items 데이터는 보존됨).

참고: Antigravity에서 별도의 이전 스크립트 (예: seed_db.py을 업데이트하는 대신 scripts/create_reservations.py을 업데이트합니다. git diff --name-only에서 scripts/의 새 스크립트를 확인하고 대신 실행합니다.

이때까지 모든 것이 제대로 작동했다면 ADK 에이전트 개발 UI에서 기능을 테스트할 수 있습니다. tools.yaml에서 새 도구 정의를 선택하려면 툴박스를 다시 시작합니다. 기존 도구 상자 프로세스를 중지한 다음 새 프로세스를 시작합니다.

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

ADK 개발 UI를 시작합니다.

uv run adk web .

브라우저에서 http://localhost:8000을 열고 다음 프롬프트로 테스트합니다.

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

검사: 에이전트가 예약 세부정보를 확인하고 예약을 생성해야 합니다.

Do I have any upcoming reservations?

검사: 에이전트가 방금 만든 예약을 나열해야 합니다.

이제 Ctrl+C를 두 번 눌러 ADK 개발 UI를 중지합니다.

체크포인트: 에이전트가 예약 및 조회 작업을 처리합니다. 전체 SDD 사이클(지정 → 명확화 → 계획 → 작업 → 분석 → 구현 → 테스트)을 완료했습니다. 각 단계에서는 specs/<branch-name>/에 버전이 지정된 아티팩트를 생성했습니다.

8. 챌린지 (선택사항)

이제 전체 SDD 워크플로를 알게 되었습니다. 테스트해 보세요.

• 두 번째 SDD 사이클을 실행하여 식당 컨시어지를 위한 웹 채팅 인터페이스를 빌드합니다. 이번에는 단계별 안내가 없습니다.
• 프로덕션 시나리오를 위해 Cloud Run에 에이전트 배포

힌트

• 프로젝트에 프런트엔드 프레임워크가 없습니다. Antigravity는 일반 HTML/CSS/JS를 제안해야 합니다. React 등을 제안하는 경우 단순성을 지향하도록 유도하세요 (헌법의 '단순하게 유지' 원칙이 이를 포착해야 함).
• ADK 서버는 스트리밍을 위해 /run_sse를, 세션 관리를 위해 /apps/{app_name}/users/{user_id}/sessions를 노출합니다. Antigravity는 프로젝트 컨텍스트에서 이를 검색합니다.
• 구현 후 정적 파일 마운트가 작동하도록 adk web이 아닌 uv run uvicorn server:app --host 0.0.0.0 --port 8080로 서버를 시작합니다.
• http://localhost:8080/static/index.html에서 테스트합니다.
• 참조 코드랩에서는 이미 ADK 에이전트를 배포하고 유지하는 방법을 보여줍니다. Antigravity에 이를 참조하세요.

9. 축하합니다.

예약 예약 기능을 사용하여 레스토랑 컨시어지 ADK 에이전트를 확장했습니다. Antigravity의 SDD 워크플로를 통해 애플리케이션 코드를 직접 작성하지 않고도 가능합니다.

빌드한 항목

• 메뉴 검색, 시맨틱 검색, 식단 선호도 추적, 예약 기능을 갖춘 레스토랑 컨시어지 ADK 에이전트
• 프로젝트 컨텍스트 문서를 생성하고 유지하는 저장소 연구용 Antigravity 스킬
• 계획 및 분석 중에 협상 불가능한 원칙을 적용하는 프로젝트 헌법
• 명시 → 명확히 하기 → 계획 → 작업 → 분석 → 구현 워크플로를 보여주는 전체 SDD 주기

학습한 내용

• Antigravity에서 사양 기반 개발 워크플로를 사용하여 기존 코드베이스에 기능을 체계적으로 추가하는 방법
• 대화 전반에서 재사용할 수 있도록 도메인 지식을 패키징하는 Antigravity 스킬을 만드는 방법
• Antigravity가 아키텍처, 패턴, 기술 선택에 대해 정보에 입각한 결정을 내릴 수 있도록 프로젝트 컨텍스트를 부트스트랩하는 방법
• SDD 워크플로가 검증하는 프로젝트 규정을 설정하는 방법
• MCP 도구 상자를 통해 새로운 데이터베이스 지원 도구로 ADK 에이전트를 확장하는 방법

삭제

실행 중인 로컬 프로세스를 중지합니다 (도구 상자).

pkill -f toolbox 2>/dev/null

지속적인 요금이 청구되지 않도록 Cloud SQL 인스턴스를 삭제합니다.

gcloud sql instances delete restaurant-db --quiet

원하는 경우 전체 프로젝트를 삭제합니다.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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