1. 소개
이 Codelab에서는 Google의 명령줄 코딩 에이전트인 Gemini 3와 Gemini CLI를 사용하여 매치 3 아케이드 게임인 CloudCrush를 빌드합니다. 게임은 Go로 작성되고 Cloud Run을 사용하여 Google Cloud에 배포됩니다.
이 Codelab의 주요 목표는 코드를 수동으로 작성하는 대신 에이전트를 오케스트레이션하여 애플리케이션을 빌드하는 기술을 개발하는 것입니다. 이러한 기술을 이전에 사용해 본 적이 없더라도 모든 개발 작업을 Gemini CLI에 위임할 수 있습니다.
이 Codelab은 에이전트형 코딩 워크플로를 배우려는 중급 개발자를 대상으로 합니다. 이 실습의 예상 총 소요 시간은 60분입니다. 이 Codelab에서 만든 리소스는 소비 기반 가격 책정을 사용합니다.
실습할 내용
- Go와 Ebitengine 프레임워크를 사용하여 핵심 Match-3 게임 로직을 빌드합니다.
- WebAssembly (WASM)를 사용하여 웹브라우저에서 실행되도록 게임을 조정합니다.
- 게임과 게임의 최고 점수 API를 Cloud Run에 배포합니다.
- 테스트 및 코드 검토를 위한 전문 하위 에이전트 및 확장 프로그램 오케스트레이션
기본 요건
- 프로그래밍 언어에 관한 기본 지식
- 클라우드 인프라에 대한 기본 지식
- Google Cloud 콘솔에 대한 기본 지식
학습할 내용
- 코딩 에이전트를 사용하여 복잡한 애플리케이션을 빌드하는 방법
- 멀티모달 컨텍스트에서 Gemini를 사용하는 방법
- Cloud Run을 사용하여 클라우드에 애플리케이션을 배포하는 방법
필요한 항목
이 워크숍은 Cloud Shell을 사용하여 클라우드에서 완전히 진행할 수 있지만, 로컬 머신을 사용하려면 다음이 필요합니다.
- Gemini CLI를 통해서도 이용할 수 있습니다. geminicli.com의 안내에 따라 다운로드하여 설치합니다.
- Go 도구 모음 (버전 1.26 이상) go.dev의 안내에 따라 다운로드하고 설치합니다.
- Google Cloud와 상호작용하는 gcloud CLI Google Cloud 문서의 안내에 따라 다운로드하고 설치합니다.
- Google Cloud 결제 계정 (게임을 클라우드에 배포)
주요 기술
여기에서 활용할 기술에 대한 자세한 내용을 확인할 수 있습니다.
- Gemini CLI: 개발 에이전트
- Gemini 3: Google의 최신 버전의 대규모 언어 모델
2. 환경 설정
프로젝트 설정
Google Cloud 프로젝트 만들기
- Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
- Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.
Cloud Shell 시작
Cloud Shell은 Google Cloud에서 실행되는 명령줄 환경으로, 필요한 도구가 미리 로드되어 제공됩니다.
- Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
- Cloud Shell에 연결되면 인증을 확인합니다.
gcloud auth list - 프로젝트가 구성되었는지 확인합니다.
gcloud config get project - 프로젝트가 예상대로 설정되지 않은 경우 설정합니다.
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
3. 프로젝트 설정
프로젝트 디렉터리 만들기
먼저 프로젝트의 새 디렉터리를 만들어야 합니다. 터미널에서 다음 명령어를 실행합니다.
mkdir -p codelab-match3 && cd codelab-match3
Gemini CLI 실행
먼저 Gemini CLI가 올바르게 설치되었는지 확인해 보겠습니다. 터미널에서 다음을 실행합니다.
gemini --version
다음과 같은 결과를 확인할 수 있습니다.
$ gemini --version 0.37.1
이제 gemini 명령어를 사용하여 Gemini CLI를 실행합니다.
gemini
Gemini CLI 프롬프트가 표시됩니다.
Gemini CLI 프롬프트가 표시되면 준비가 완료된 것입니다. 그렇지 않은 경우 이전 설정 단계를 놓친 부분이 없는지 다시 한번 확인하세요.
모델 조정 사용 설정
모델 조종은 에이전트가 특정 작업을 처리하는 동안 에이전트에 추가 컨텍스트를 추가할 수 있는 기능입니다. 이를 사용하여 에이전트가 잘못된 방향으로 진행되는 경우 에이전트를 수정하거나, 에이전트 응답을 개선하기 위해 명확한 정보를 추가하거나, 원래 프롬프트에서 누락된 사소한 기능을 포함할 수 있습니다.
모델 조정을 사용 설정하려면 /settings 명령어를 사용하여 설정 메뉴를 열고 검색창에 '조정'을 입력하세요. 그런 다음 모델 조향 사용 옵션을 true로 설정합니다.
변경사항을 적용하려면 CLI를 다시 시작해야 할 수도 있습니다('r' 키 누르기).
애셋 다운로드
게임에서 사용할 이미지를 다운로드해야 합니다. 파일은 여기의 저장소에 GitHub에 저장되어 있습니다. 수동으로 다운로드하거나 다음 프롬프트를 사용하여 Gemini에게 다운로드해 달라고 요청할 수 있습니다.
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
4. 계획 모드 및 모델 조향으로 게임 만들기
먼저 핵심 Match-3 게임 로직을 빌드합니다. 복잡한 작업이므로 계획 모드에서 Gemini CLI를 사용하여 개발을 오케스트레이션하는 것이 좋습니다.
Gemini CLI 프롬프트에서 슬래시 명령어 /plan를 사용하여 계획 모드를 전환합니다.
/plan
계획 모드를 사용 설정한 상태에서 다음 프롬프트를 복사하여 Gemini 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.
Gemini CLI는 계획을 생성하기 전에 몇 가지 명확히 하기 위한 질문을 할 수 있습니다.
예를 들어 단일 파일 애플리케이션을 선호하는지 아니면 다중 파일 애플리케이션을 선호하는지 묻습니다.
애니메이션 환경설정에 관해 묻는 메시지가 표시됩니다.
마지막 질문은 go:embed를 사용하여 애셋을 바이너리 자체에 삽입하는 것입니다.
모든 질문에 답변한 후 Enter 키를 눌러 제출하기 전에 마지막으로 검토할 수 있습니다.
계획이 완료되면 검토하라는 메시지가 표시됩니다.
검토 상자 하단에는 계획을 그대로 수락하거나 Google의 의견을 추가할 수 있는 옵션이 있습니다.
이 기회를 활용하여 원래 프롬프트에서 누락된 새로운 요구사항을 추가하세요.
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.
마지막으로 구현 계획을 확인하라는 메시지가 표시됩니다.
Enter 키를 눌러 에이전트가 작업을 시작하도록 합니다. 이제 에이전트가 계획 모드를 종료하고 코드 작성을 시작합니다.
이 시점에서 구현을 변경하려면 일반적으로 완료될 때까지 기다리거나 ESC 키로 중단해야 하지만 모델 조향이 사용 설정되어 있으므로 모델을 수정하는 명령어를 대기열에 추가할 수 있습니다.
에이전트가 작동하는 동안 에이전트 채팅 창에 다음을 붙여넣어 '모델 조향' 기능을 시연하고 구현을 전환하기 위해 명령어를 대기열에 추가하는 방법을 보여줍니다.
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.
이 프롬프트가 '조향 힌트'로 대기열에 추가됩니다.
계획을 수락하고 에이전트가 모든 요구사항을 구현하는 것을 지켜보세요.
에이전트가 구현을 완료하면 프로젝트 폴더에서 go run main.go를 실행하여 데스크톱 버전을 데모로 보여줍니다. 이 명령어를 실행하기 위해 Gemini CLI를 종료할 필요는 없습니다. !를 입력합니다. (느낌표)를 입력하여 셸 모드로 전환하고 거기에서 명령어를 실행합니다.
셸 모드에서 실행하면 발생할 수 있는 문제가 에이전트 컨텍스트에 즉시 포착된다는 장점이 있습니다. 예를 들어 이 경우 에이전트가 일부 종속 항목을 다운로드하는 것을 잊었습니다.
이스케이프 키를 눌러 셸 모드를 종료한 후 에이전트에게 오류를 검사하고 수정해 달라고 요청할 수 있습니다.
성공적인 결과는 다음과 유사하게 표시됩니다.
게임 매개변수를 미세 조정하여 만족스러운 경험을 얻을 때까지 게임을 플레이해 보세요 (예: 애니메이션 속도를 빠르게 또는 느리게 조정, 명령어에 대한 반응 방식 조정 등).
5. 웹브라우저에서 실행되도록 게임을 조정합니다.
방금 만든 Ebitengine 게임은 데스크톱 애플리케이션입니다. 웹에서 실행되도록 하려면 WebAssembly로 변환하면 됩니다.
다음 프롬프트를 사용하여 에이전트를 안내하세요.
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.
에이전트가 작업을 완료하면 에이전트가 백그라운드에서 게임 서버를 실행하도록 지시할 수 있습니다.
Ctrl+B 키 조합을 사용하여 백그라운드 프로세스를 관리할 수 있습니다.
이 창을 닫으려면 Ctrl+B를 다시 누르세요.
이제 브라우저에서 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).
다음은 타이틀 화면의 예입니다.
이제 좀 더 전문적으로 보입니다. 🙂
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 button to generate a random name and
a confirmation button to the name entry.
Also 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.
브라우저에서 게임을 다시 실행합니다. QR 코드를 사용하여 휴대기기에서도 게임에 액세스해 보세요.
8. 브라우저 에이전트를 사용하여 게임 테스트
Gemini CLI에서 하위 에이전트는 현재 컨텍스트가 결과에 영향을 미치지 않도록 하려는 장기 실행 작업 또는 높은 정밀도가 필요한 작업에 적합한 새로운 컨텍스트가 있는 격리된 페르소나입니다.
게임은 기존 테스트 도구 (예: 단위 및 통합 테스트)로 테스트하기 어렵지만 브라우저 에이전트를 사용하여 일부 테스트를 실행할 수 있습니다. 브라우저 에이전트는 자체 Chrome 브라우저를 스핀업할 수 있으며 DOM 명령어를 실행하여 게임 화면을 탐색합니다. 스크린샷을 찍는 기능도 있어 테스트를 문서화하는 데 사용할 수 있으며, 나중에 UI를 약간 조정할 수 있도록 상담사에게 다시 제공할 수도 있습니다.
브라우저 에이전트는 현재 실험 단계이므로 먼저 사용 설정해야 합니다. 프로젝트 수준에서 에이전트를 사용 설정하려면 Gemini CLI에 다음 프롬프트를 입력하세요.
Create a .gemini/settings.json file with the following content to
configure the browser sub agent:
{
"agents": {
"overrides": {
"browser_agent": {
"enabled": true
}
}
}
}
이 변경사항을 적용하려면 에이전트를 다시 시작해야 합니다. /chat save 명령어를 사용하여 현재 대화를 저장합니다.
Ctrl+D를 두 번 눌러 Gemini CLI를 종료하고 다시 시작합니다. /chat resume cloud-crush와의 대화를 복원합니다.
이제 브라우저 에이전트에 액세스할 수 있습니다. 브라우저 에이전트에게 작업을 위임하려면 언제든지 @browser_agent로 언급하면 됩니다.
이제 브라우저 에이전트를 사용하여 배포된 게임을 평가합니다.
@browser_agent perform an end-to-end test of the Cloud Run deployment URL.
Navigate the homepage, start a game, submit a score, and verify the new score
appears correctly on the leaderboard. Take screenshots to show each step of the
investigation and save to ./screenshots.
확인 화면이 표시됩니다.
상담사와 필요한 도구에 동의하면 새 Chrome 브라우저 창이 열립니다. 에이전트가 제어하는 브라우저입니다. 시각적 힌트는 화면의 파란색 테두리와 하단의 'Gemini CLI가 이 브라우저를 제어하고 있습니다'라는 메시지입니다.
완료되면 다음과 같은 메시지가 표시됩니다.
다음은 브라우저 에이전트가 촬영한 스크린샷입니다.
title_screen.png:
game_board.png:
이제 에이전트가 촬영한 이미지 중 하나를 사용하여 게임 UI를 최적화할 수 있습니다. 예를 들면 다음과 같이 말하세요.
Analyse the screenshot @screenshots/game_board.png and adjust the side panel to
have better contrast and be more harmonic with the rest of UI elements. Focus
on readability and color theory to achieve the best possible visuals.
9. 게임을 보호하기 위한 맞춤 에이전트 만들기
'바이브 코딩' 애플리케이션의 일반적인 우려사항 중 하나는 코딩 및 보안 관점에서 높은 품질과 권장사항을 유지하는 방법입니다. 이 두 측면에서 매우 엄격한 프롬프트를 작성할 수는 있지만 프롬프트에 추가할수록 에이전트의 집중도가 떨어져 최적이 아닌 결과가 나오는 경우가 많습니다. 이러한 유형의 시나리오에서는 하위 에이전트가 기본 에이전트와 별도의 컨텍스트에서 작동하고 개발자가 부여한 작업에 집중할 수 있으므로 하위 에이전트를 사용하는 것이 이상적입니다. 이 코드에 대한 보안 감사를 실행하고 이 게임을 Cloud Run에 배포하는 동안 사용자 인증 정보가 유출되거나 불필요한 위험에 노출되지 않도록 맞춤 에이전트를 만들어 보겠습니다.
Create a new custom agent in .gemini/agents/security_auditor.md using the following content:
---
name: security_auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
- read_file
- grep_search
model: gemini-3-flash-preview
temperature: 0.2
max_turns: 10
---
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.
변경사항을 적용하려면 CLI를 다시 시작해야 합니다. 이전과 마찬가지로 /chat save로 채팅 세션을 저장하고 /chat resume로 다시 시작합니다.
CLI가 재개되면 시작 시 새 에이전트가 자동으로 감지됩니다.
Acknowledge and Enable를 클릭한 다음 에이전트에게 다음 프롬프트로 게임 코드에 대한 보안 검사를 실행해 달라고 요청합니다.
@security-auditor please run a security audit on this code and cloud run
deployment to make sure it is safe against common attack patterns and that it is
not leaking any credentials
다음과 같은 결과를 확인할 수 있습니다.
감사가 완료되면 추천이 제공됩니다. 이 예에서는 실제로 수정해야 할 몇 가지 중요한 사항을 발견했습니다.
발견한 사항이 있으면 Gemini CLI에 수정해 달라고 요청하면 됩니다. 🙂
10. 결론
축하합니다. Gemini CLI를 사용하여 아케이드 게임을 빌드, 배포, 테스트, 감사하여 초기 스캐폴딩부터 배포까지 고급 에이전트 워크플로를 시연했습니다.
삭제
나중에 이 Codelab으로 돌아오지 않을 계획이라면 이 Codelab에서 만든 리소스를 삭제하는 것이 좋습니다.
- Cloud Run 서비스를 삭제합니다.
Gemini CLI에 삭제를 요청합니다.
I'm finished with this project. Delete the cloud run deployment.
- 프로젝트 디렉터리를 삭제합니다.
cd .. && rm -rf codelab-match3
또는 이 Codelab만을 위해 만든 Google Cloud 프로젝트인 경우 전체 프로젝트를 삭제할 수 있습니다.
다음 단계
이 플랫폼에서 다른 Codelab을 살펴보거나 직접 Cloud Crush를 개선하여 학습 여정을 이어갈 수 있습니다.
게임을 개선하기 위한 몇 가지 제안사항은 다음과 같습니다.
- 4개 이상의 Gem이 일치할 때 표시되는 특수 'Gemini' Gem (gemini.png 사용)을 추가합니다. Gemini 보석을 3개 이상 맞추면 보너스 시간이 주어집니다.
- 음악을 추가합니다. Gemini 홈페이지에서 Lyria 3를 사용하여 음악을 생성할 수 있습니다.
- 음향 효과 추가
- 다른 게임 플레이 모드 추가
즐겁게 코딩해 보세요!