1. 소개
이 Codelab에서는 Gemini 3와 Antigravity 코딩 에이전트를 사용하여 매치 3 아케이드 게임인 CloudCrush를 빌드합니다. 게임은 Go로 작성되고 Cloud Run을 사용하여 Google Cloud에 배포됩니다.
Go 언어에 대한 지식이 있으면 좋지만, 에이전트가 모든 코딩을 수행하므로 이 워크숍을 진행하는 데 필수 사항은 아닙니다. 이 Codelab의 주요 목표는 코드를 수동으로 작성하는 대신 에이전트를 오케스트레이션하여 애플리케이션을 빌드하는 기술을 개발하는 것입니다.
이 Codelab은 고급 에이전트 워크플로를 배우려는 중급 개발자를 대상으로 합니다. 이 실습의 예상 총 소요 시간은 60분입니다. 이 Codelab에서 만든 리소스는 소비 기반 가격 책정을 사용합니다.
실습할 내용
- Go와 Ebitengine 프레임워크를 사용하여 핵심 매치3 게임 로직을 빌드합니다.
- WebAssembly (WASM)를 사용하여 웹브라우저에서 실행되도록 게임을 조정합니다.
- 게임과 게임의 최고 점수 API를 Cloud Run에 배포합니다.
- 테스트 및 코드 검토를 위한 전문 하위 에이전트 및 확장 프로그램 오케스트레이션
기본 요건
- 프로그래밍 언어에 관한 기본 지식
- 클라우드 인프라에 대한 기본 지식
- Google Cloud 콘솔에 대한 기본 지식
학습할 내용
- 코딩 에이전트를 사용하여 복잡한 애플리케이션을 빌드하는 방법
- 멀티모달 컨텍스트에서 Gemini를 사용하는 방법
- Cloud Run을 사용하여 클라우드에 애플리케이션을 배포하는 방법
필요한 항목
이 워크숍은 Cloud Shell을 사용하여 클라우드에서 완전히 진행할 수 있지만, 로컬 머신을 사용하려면 다음이 필요합니다.
- Antigravity 2.0 및 Antigravity CLI antigravity.google의 안내에 따라 다운로드하여 설치합니다.
- Go 도구 모음 (버전 1.26 이상) go.dev의 안내에 따라 다운로드하고 설치합니다.
- Google Cloud와 상호작용하는 gcloud CLI Google Cloud 문서의 안내에 따라 다운로드하고 설치합니다.
- Google Cloud 결제 계정 (게임을 클라우드에 배포)
주요 기술
여기에서 활용할 기술에 대한 자세한 내용을 확인할 수 있습니다.
- Antigravity CLI: 개발 에이전트
- Gemini 3: Google의 최신 버전의 대규모 언어 모델
2. 환경 설정
자체 머신에서 이 Codelab을 실행하려면 자체 속도 환경 설정을 선택하고, 클라우드에서 이 Codelab을 완전히 실행하려면 Cloud Shell 시작을 선택합니다.
자습형 환경 설정
- Google Cloud Console에 로그인하여 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Gmail이나 Google Workspace 계정이 없는 경우 계정을 만들어야 합니다.
- 프로젝트 이름은 이 프로젝트 참가자의 표시 이름입니다. 이는 Google API에서 사용하지 않는 문자열이며 언제든지 업데이트할 수 있습니다.
- 프로젝트 ID는 모든 Google Cloud 프로젝트에서 고유하며, 변경할 수 없습니다(설정된 후에는 변경할 수 없음). Cloud 콘솔은 고유한 문자열을 자동으로 생성합니다. 일반적으로는 신경 쓰지 않아도 됩니다. 대부분의 Codelab에서는 프로젝트 ID (일반적으로
PROJECT_ID로 식별됨)를 참조해야 합니다. 생성된 ID가 마음에 들지 않으면 다른 임의 ID를 생성할 수 있습니다. 또는 직접 시도해 보고 사용 가능한지 확인할 수도 있습니다. 이 단계 이후에는 변경할 수 없으며 프로젝트 기간 동안 유지됩니다. - 참고로 세 번째 값은 일부 API에서 사용하는 프로젝트 번호입니다. 이 세 가지 값에 대한 자세한 내용은 문서를 참고하세요.
- 다음으로 Cloud 리소스/API를 사용하려면 Cloud 콘솔에서 결제를 사용 설정해야 합니다. 이 Codelab 실행에는 많은 비용이 들지 않습니다. 이 튜토리얼이 끝난 후에 요금이 청구되지 않도록 리소스를 종료하려면 만든 리소스 또는 프로젝트를 삭제하면 됩니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다.
Cloud Shell 시작
Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.
Google Cloud Console의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.
가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.
3. 프로젝트 설정
프로젝트 디렉터리 만들기
먼저 프로젝트의 새 디렉터리를 만들어야 합니다. 터미널에서 다음 명령어를 실행합니다.
mkdir -p codelab-match3 && cd codelab-match3
Antigravity CLI 실행
먼저 Antigravity CLI가 올바르게 설치되었는지 확인합니다. 터미널에서 다음을 실행합니다.
agy --version
다음과 같은 결과를 확인할 수 있습니다.
$ agy --version 1.0.2
이제 agy 명령어를 사용하여 Antigravity CLI를 실행합니다.
agy
Antigravity에서 이 프로젝트를 신뢰할 수 있는지 묻습니다. 방금 빈 폴더를 만들었으므로 신뢰해도 됩니다. 액세스를 확인하면 CLI 프롬프트로 이동합니다.
Antigravity CLI 프롬프트가 표시되면 준비가 완료된 것입니다. 그렇지 않은 경우 이전 설정 단계를 놓치지 않았는지 다시 확인하세요.
4. 계획 모드에서 기본 게임 만들기
먼저 핵심 매치-3 게임 로직을 빌드해 보겠습니다. 안티그래비티는 기본적으로 계획 모드로 시작되므로 계획으로 전환하기 위해 특별한 명령어를 실행할 필요가 없습니다.
하지만 Antigravity CLI 프롬프트에서 슬래시 명령어 /planning를 사용하여 언제든지 계획 모드를 사용 설정할 수 있다는 점을 알아두면 유용합니다.
/planning
지금 이 명령어를 실행하면 Antigravity에서 이미 계획 중이라고 알려줍니다.
계획 모드의 반대는 빠른 모드이며, /fast를 사용하여 사용 설정할 수 있습니다.
/fast
빠른 모드에서는 Antigravity가 즉시 작업을 시작하며, 간단한 독립형 작업에 적합합니다. 계획 모드는 복잡한 작업을 위해 설계되었습니다. 에이전트가 먼저 계획을 자세히 설명하면 사용자가 실행 전에 검토하고 반복할 수 있습니다.
애셋 다운로드
게임에서 사용할 이미지를 다운로드해야 합니다. 이는 작은 독립형 작업이므로 계획 모드에서 실행할 필요가 없습니다. 빠른 모드에 있다는 점을 활용하여 바로 실행해 보겠습니다.
Create a folder named "assets" and download the images
background.png, gcp_sprites.png, gemini.png and logo.png,
from this GitHub repository to the "assets" folder:
https://github.com/GoogleCloudPlatform/devrel-demos/tree/main/codelabs/gemini-cli/gemini-cli-match3-golang
Antigravity에서 파일을 다운로드하기 위해 몇 가지 셸 명령어를 실행할 권한을 요청합니다. 완료되면 다음과 같이 표시됩니다.
기본 게임 만들기
애셋이 준비되었으므로 이제 기본 게임을 빌드할 차례입니다. 게임을 빌드하는 것은 상당히 복잡한 작업이므로 프롬프트를 제공하기 전에 계획 모드로 돌아가겠습니다.
/planning
계획 모드에서 다음 프롬프트를 Antigravity CLI에 복사하여 붙여넣습니다.
Build a Match-3 game called 'Cloud Crush' in Go using Ebitengine v2.
The entire game screen should have background.png as background.
The play area should be an 8x8 grid with white background.
On the right side of the play area include a side panel with UI elements
like player score and how to play instructions.
The side panel should have a solid background colour to help with readability of the UI.
Use standard GCP product logos (e.g. Compute Engine, Cloud Storage, BigQuery, etc.)
as icons. These icons are provided in the gcp_sprites.png file.
The icons are saved as 64x64 sprites but scale them as necessary
based on the screen resolution. Implement swapping, clearing 3+ gems, and gravity.
Use ebitengine native font rendering (size 48 for titles and size
24 for normal text) for all text and not the debug print.
The font should be monospaced (golang.org/x/image/font/gofont/gomono).
Keep the UI tidy and harmonic, e.g. centered text should always be
adjusted based on text length, not just guess based on estimates.
계획을 세우기 전에 PNG 파일을 검사하여 크기를 확인하는 등 탐색을 할 수 있습니다. 계획이 완료되면 검토하라는 메시지가 표시됩니다.
오른쪽 하단에 아티팩트 1개라고 작성되어 있고 /artifact를 사용하여 검토하라는 힌트가 표시되어 있습니다. Antigravity에서는 계획, 작업 목록, 둘러보기와 같은 지원 파일을 솔루션의 일부인 일반 파일 (예: 소스 코드)과 구분하기 위해 '아티팩트'라고 합니다.
프롬프트에 /artifact 명령어를 입력하면 계획을 확인하고 조정이 필요한 경우 댓글을 달 수 있습니다.
/artifact
다음과 같은 결과를 확인할 수 있습니다.
열기, 승인 또는 거부 옵션이 있는 implementation_plan.md라는 파일이 있습니다. Enter 키를 눌러 엽니다. 다음은 내 시스템에서 계획이 표시되는 방식의 예입니다.
화살표 키를 사용하여 위아래로 스크롤할 수 있으며, 어느 줄에서든 C 키를 눌러 댓글을 추가할 수 있습니다. 이 경우 이전 버전의 Go를 사용하는 것이 마음에 들지 않으므로 16번째 줄에 Go 1.26 (이 글을 쓰는 시점의 최신 버전)을 사용하라는 주석을 추가합니다.
댓글을 입력하면 인라인으로 표시됩니다.
확인해야 할 중요한 섹션은 '인증 계획'입니다. 게임은 자동으로 테스트하기가 어렵지만 Go는 컴파일된 언어이므로 모델이 컴파일되는 코드를 전달하는지 최소한 확인해야 합니다. 바이너리 빌드를 위한 자동화된 단계가 포함되지 않은 경우 주석으로 추가합니다.
확인해야 할 중요한 섹션은 '인증 계획'입니다. 게임은 자동 테스트가 어렵지만 Go는 컴파일된 언어이므로 모델이 컴파일되는 코드를 전달하는지 최소한 확인해야 합니다. 바이너리 빌드를 위한 자동화된 단계가 포함되지 않은 경우 주석으로 추가합니다.
계획이 만족스러울 때까지 이 과정을 반복한 다음 ESC 키를 눌러 돌아갑니다. 그런 다음 Y를 눌러 상담사에게 댓글을 전송하는 것을 확인합니다.
Y를 누르면 에이전트가 즉시 작동하기 시작합니다. '아티팩트' 메뉴를 종료하려면 Esc 키를 한 번 더 눌러야 합니다. 그러면 프롬프트 모드로 돌아갑니다. 한편, 에이전트는 셸 명령어를 실행해야 하므로 훨씬 더 많은 도구 호출 확인을 요청할 수 있습니다.
기다리는 동안 프롬프트를 대기열에 추가하여 디자인 작업을 계속할 수도 있습니다. 예를 들어 이 기회를 활용하여 원래 프롬프트에서 누락된 새로운 요구사항을 추가할 수 있습니다.
Add a 60-seconds countdown timer and an in-memory high-score tracker to enhance the arcade game experience. Combos should give a score bonus of 10% per combo number.
대기열에 추가된 프롬프트는 메시지 기록에 표시되며, 앞에 작은 화살표가 있습니다.
아티팩트 수가 증가하는 것도 확인할 수 있습니다. 계획 외에도 Antigravity는 구현해야 하는 각 항목이나 수행해야 하는 할 일을 추적하기 위해 할 일 목록 (task.md)을 만듭니다. 완료되면 달성한 목표를 설명하는 둘러보기 파일 (walkthrough.md)을 만듭니다. /artifact 명령어를 다시 사용하여 이 모든 항목을 검사할 수 있습니다.
기본 게임 구현을 완료한 후의 task.md 파일의 예는 다음과 같습니다.
언제든지 이러한 파일을 열고 댓글을 추가할 수 있으며, 상담사에게 전송되면 대기열에 추가된 프롬프트와 마찬가지로 실행을 위해 대기열에 추가됩니다. 이 파일에 댓글을 달아 에이전트에게 요청에 관한 추가 컨텍스트를 제공하는 것이 좋습니다.
바이너리가 성공적으로 빌드되면 다음과 같이 표시됩니다.
게임을 실행하여 예상대로 작동하는지 확인합니다. 에이전트 프롬프트 내에서 실행하는 것이 좋습니다. 느낌표 '!'를 입력하여 프롬프트를 '셸 모드'로 전환할 수 있습니다.
프롬프트 아래에 '활성화된 bash 모드'라는 메시지가 표시됩니다. Enter 키를 눌러 명령어를 실행합니다. 이 모드에서 바이너리를 실행하면 에이전트가 터미널의 출력을 '감시'하므로 게임 실행이 실패하거나 갑자기 비정상 종료되는 경우 에이전트에게 발생한 문제를 설명할 필요가 없습니다. 그러면 셸 컨텍스트에서 필요한 모든 정보가 즉시 제공됩니다.
게임 매개변수를 미세 조정하여 만족스러운 경험을 얻을 때까지 게임을 플레이해 보세요 (예: 애니메이션 속도를 빠르게 또는 느리게 조정, 명령어에 대한 반응 방식 조정 등).
예를 들어 이 프롬프트는 접근성 모드와 새로운 키보드 명령어를 추가하여 환경을 개선합니다.
Update the implementation to include: 'Q' to quit, 'F' for full-screen
and 'A' for Accessibility Mode: swap GCP logos for high-contrast coloured blocks.
Also enable Arrow Keys to move the selection cursor and Space to select the gem to
swap (space is pressed once to select, then arrow key immediately makes
the move - no need to press space again).
Use a golden square (4 px border, transparent fill) with a simple animation
to highlight where the cursor is at the moment.
다듬기가 끝나면 다음 섹션으로 이동하여 웹 앱으로 변환합니다.
5. 웹브라우저에서 실행되도록 게임을 조정합니다.
Ebitengine 게임은 현재 데스크톱 애플리케이션입니다. Antigravity CLI에 WebAssembly (WASM)를 사용하여 웹브라우저에서 실행되도록 적용해 달라고 요청해 보겠습니다. 여기에는 브라우저 타겟용 Go 코드 컴파일과 기본 웹 서버 설정이 포함됩니다.
다음 프롬프트를 사용하여 에이전트를 안내합니다.
We need to enable this game to run on a web browser. Compile the game to WASM
and create a Go web server to serve the compiled WASM and the assets.
에이전트가 파일 시스템에서 wasm_exec.js라는 파일을 찾으려고 시도합니다. 이 파일은 JS를 통해 Go 바이너리를 실행할 수 있도록 지원하는 래퍼이므로 허용해야 합니다. 예를 들면 다음과 같습니다.
에이전트가 작업을 완료하면 에이전트에게 백그라운드에서 게임 서버를 실행하도록 지시할 수 있습니다.
이제 브라우저에서 http://localhost:8080을 열어 웹에서 실행되는 게임을 확인합니다.
이제 웹에서 실행되므로 클라우드에 배포하기 전에 최종적으로 다듬어 보겠습니다.
6. 제목 화면 및 리더보드 만들기
게임은 작동하지만 적절한 아케이드 환경을 위한 몇 가지 주요 기능이 누락되어 있습니다. 먼저 제목 화면을 추가한 다음 친구와 경쟁할 수 있도록 리더보드를 추가해 보겠습니다. 다음 프롬프트를 사용하세요.
Create a title screen that displays the game logo (logo.png) over the cloud background.
The logo should be centered and occupy no more than 75% of the screen area.
The title screen should display "Press ENTER to play" (black/bold) right below the logo,
with every letter animated in a slow wavy (cosine) pattern.
Once the player presses ENTER, it should be prompted to add their name, which
will then be recorded to populate the leaderboard at the end of the round.
Once the game is over, play the animated leaderboard with the top 10 highest scores.
The animated leaderboard should render entries one by one up to 10 entries,
using a fade in effect just like old school arcade games. The leaderboard
should fade out to the title screen after 15 seconds.
Please note that name entry should be processed independently of the play state
key handlers (e.g. pressing A during name entry should not toggle accessibility mode).
Leaderboard scores should be saved in-memory, server-side.
이제 좀 더 전문적으로 보입니다. 🙂
7. Cloud Run에 게임 배포
이제 드디어 전 세계와 내가 만든 작품을 공유할 시간입니다. 어디서나 액세스할 수 있도록 전체 애플리케이션을 Google Cloud Run에 배포합니다.
Use the gcloud CLI to provision and deploy the Go web server and its assets to
Google Cloud Run. Provide the live URL when complete.
이제 게임이 클라우드에서 라이브로 제공되므로 휴대기기에서 실행할 수 없으면 기회를 놓치는 것입니다. 다음 프롬프트를 사용하면 됩니다.
Now enable this game to run on mobile devices. You need to update the input system to handle "taps" as well as key presses and clicks. Since mobile devices most likely won't have a keyboard, add a virtual keyboard to the name entry screen and a confirmation button to the name entry.
Finally, generate a QR code for the CloudRun link and display it on the screen so that people can scan it to access the mobile version and compete against their friends for the high score.
브라우저에서 게임을 다시 실행합니다. 휴대기기에서도 URL에 액세스해 보세요. QR 코드를 생성하면 이 환경을 간소화할 수 있습니다.
8. 브라우저 에이전트를 사용하여 게임 테스트
게임은 시각적 피드백에 의존하므로 자동 테스트가 어려운 경우가 많지만, 자동화를 활용하여 배포가 올바르게 작동하고 기본 요소가 마련되어 있는지 확인할 수 있습니다.
이를 위해 브라우저 하위 에이전트를 사용합니다. Antigravity에서 하위 에이전트는 새 컨텍스트가 있는 격리된 페르소나로, 현재 컨텍스트가 결과에 영향을 미치지 않도록 하거나 작업이 기본 컨텍스트 윈도우를 '오염'시키지 않도록 하려는 작업에 적합합니다.
브라우저 에이전트는 브라우저 관련 작업을 위한 특별한 내장 에이전트입니다. 이 단계에서는 브라우저 에이전트를 명령줄에서 현재 사용할 수 없으므로 Antigravity 데스크톱 앱을 사용해야 합니다.
Antigravity 데스크톱 앱을 열고 Cloud Crush 프로젝트에서 새 대화를 시작합니다.
/browser를 입력한 후 다음 프롬프트를 입력하여 브라우저 하위 에이전트를 트리거할 수 있습니다.
Go to http://localhost:8080 and capture screenshots of the following game screens:
1. Title Screen (initial state: "PRESS ENTER TO PLAY")
2. Name Entry Screen (press Enter to reach this screen)
3. Main Gameplay Screen (type a name like "PLAYER" and press Enter to start)
4. Leaderboard Screen (let the game timer run out to view the high scores)
이 접근 방식을 사용하면 스크린샷을 사용하여 텍스트만으로는 설명하기 어려울 수 있는 UI 요소를 수정할 수 있습니다.
'@' 기호 다음에 파일 이름을 입력하여 파일을 참조할 수 있습니다. 예를 들어 다음과 같이 에이전트에게 제목 화면의 로고 크기를 늘려 달라고 요청할 수 있습니다.
이 예는 모델이 크기에 50% 보정을 적용하기 위해 이미지를 '볼' 필요가 없으므로 약간 인위적이지만, 텍스트 형식으로 문제를 설명하기 어려운 경우 UI를 조정하는 데 유용한 기술입니다. 또한 에이전트가 전후 스크린샷을 찍어 자체 작업을 검증할 수 있으므로 이 방법을 도구 상자에 보관하세요.
9. 게임을 보호하기 위한 맞춤 에이전트 만들기
'바이브 코딩' 애플리케이션의 일반적인 우려사항 중 하나는 코딩 및 보안 관점에서 높은 품질과 권장사항을 유지하는 방법입니다. 이 두 측면에서 매우 엄격한 프롬프트를 작성할 수 있지만 프롬프트에 추가할수록 에이전트의 집중도가 떨어져 최적의 결과가 나오지 않는 경우가 많습니다.
이러한 유형의 시나리오에서는 하위 에이전트가 이상적입니다. 하위 에이전트는 사용자가 부여한 작업에 집중할 수 있기 때문입니다. 이 코드에 대한 보안 감사를 실행하고 이 게임을 배포하는 동안 사용자 인증 정보를 유출하거나 불필요한 위험에 노출되지 않도록 맞춤 에이전트를 만들어 보겠습니다.
이 프롬프트는 에이전트의 좋은 기준을 제공합니다.
create a new subagent called "security_auditor" using the following instructions:
You are a ruthless Security Auditor. Your job is to analyze code for potential vulnerabilities.
Focus on:
1. SQL Injection
2. XSS (Cross-Site Scripting)
3. Hardcoded credentials
4. Unsafe file operations
When you find a vulnerability, explain it clearly and suggest a fix. Do not fix it yourself; just report it.
Antigravity는 'DefineSubagent' 도구를 사용하여 새 에이전트를 만듭니다.
다음 프롬프트로 에이전트에게 게임 코드에 대한 보안 검사를 요청합니다.
Run the security auditor agent in this code
다음과 같은 결과를 확인할 수 있습니다.
에이전트가 작업을 완료하면 다음과 같은 보고서가 표시됩니다.
Antigravity에 문제를 해결해 달라고 요청해 보겠습니다 🙂:
Fix these findings for me please!
다음과 같이 표시됩니다.
이 방식으로 생성된 에이전트는 대화가 진행되는 동안만 존재합니다. 세션 간에 '재사용'할 수 있는 에이전트를 사용하려면 구성 파일을 사용하여 에이전트를 만들면 됩니다. 자세한 내용은 /agents 명령어를 참고하세요.
10. 결론
축하합니다. Antigravity CLI를 사용하여 아케이드 게임을 빌드, 배포, 테스트, 감사하여 초기 스캐폴딩부터 배포까지 고급 에이전트 워크플로를 시연했습니다.
삭제
Google Cloud 계정에 지속적으로 비용이 청구되지 않도록 하려면 이 Codelab 중에 만든 리소스를 삭제하세요.
- Cloud Run 서비스를 삭제합니다.
I'm finished with this project. Delete the cloud run deployment.
- 프로젝트 디렉터리를 삭제합니다.
cd .. && rm -rf codelab-match3
또는 이 Codelab만을 위해 만든 Google Cloud 프로젝트인 경우 전체 프로젝트를 삭제할 수 있습니다.
다음 단계
이 플랫폼에서 다른 Codelab을 살펴보거나 직접 Cloud Crush를 개선하여 학습 여정을 계속할 수 있습니다. 단, 리소스 사용이 끝나면 리소스를 정리하는 것을 잊지 마세요.
즐겁게 코딩해 보세요!