1. 소개 및 설정
환영합니다
안녕하세요. 코딩 잼에 오신 것을 환영합니다. 다음 75분 동안 실제 작동하는 AI 웹 앱을 빌드합니다.
웹사이트는 여기를 참고하세요. 코딩 잼 웹사이트
빌드할 항목
이번 주의 프로젝트 브리프를 기반으로 하는 AI 기반 웹 앱 브라우저에서 실행됩니다. Google의 Gemini AI를 사용합니다. 세션이 끝나면 완전히 내 소유가 됩니다.
Antigravity 설치
Antigravity는 모든 작업에 사용할 AI 어시스턴트입니다. 컴퓨터에 설치하는 앱입니다.
1단계 — 다운로드
👉 브라우저에서 https://antigravity.google/download로 이동합니다.
👉 운영체제 (Mac, Windows, Linux)에 맞는 다운로드 버튼을 클릭합니다.
👉 다운로드한 설치 프로그램을 실행합니다. 기본 설정이 적합함 - 기본 설정을 클릭합니다.
2단계: 실행 및 로그인
👉 애플리케이션 폴더 (Mac) 또는 시작 메뉴 (Windows)에서 Antigravity를 실행합니다.
👉 메시지가 표시되면 '로그인'을 클릭합니다.
👉 Google 계정을 사용합니다.
3단계: 시작 화면 확인
세 개의 큰 버튼이 있는 Antigravity의 시작 화면이 표시됩니다.
- 폴더 열기 - 기존 폴더를 작업공간으로 엽니다.
- 상담사 관리자 열기: 상담사 대시보드로 이동합니다. 대부분의 작업이 여기서 이루어집니다.
- 저장소 클론 - GitHub에서 프로젝트를 다운로드합니다 (3A 섹션에서 사용).
자세한 내용은 https://antigravity.google/에서 확인하세요.
✅ 체크포인트: Antigravity가 설치되어 있고, 로그인되어 있으며, 3개의 버튼이 있는 시작 화면이 표시됩니다.
2. 필수 도구 설치 (Antigravity를 통해)
Antigravity를 사용하려면 컴퓨터에 두 가지 도구가 필요합니다.
도구 | 정의 (일반 영어) |
uv | 앱 백엔드의 언어인 Python을 관리합니다. |
git | 인터넷에서 프로젝트 파일을 다운로드합니다 (Antigravity는 클론에 사용). |
설치 명령어를 직접 입력하지 않아도 됩니다. 영어로 Antigravity에 요청하면 나머지는 Antigravity가 처리합니다.
1단계: 임시 작업공간 열기
Antigravity에서 채팅을 하려면 폴더가 열려 있어야 합니다. (폴더가 없으면 채팅도 없습니다.)
👉 시작 화면에서 폴더 열기를 클릭합니다.
비어 있는 폴더를 만들거나 선택합니다. 권장: 편리한 위치 (예: 데스크톱)에 coding-jam-setup이라는 새 폴더를 만듭니다.
👉 열기 (또는 폴더 선택)을 클릭합니다.
새로운 빈 작업공간이 선택된 상태로 Agent Manager 뷰가 열립니다.
2단계 — Antigravity에 도구 확인 및 설치 요청
👉 Cmd+L (Mac) 또는 Ctrl+L (Win/Linux)을 눌러 채팅 입력에 포커스를 맞춥니다.
👉 하단의 모델 선택 도구에 Gemini 3 Flash가 표시되는지 확인합니다 (기본값이며 이 경우에 적합함).
📝 가장 간단한 프롬프트 — 채팅에 다음을 붙여넣으세요.
Install uv and git on my computer if they're not already there.
Don't install Node.js. Ask permission before each install command.
📝 더 자세한 버전 (원하는 경우):
Check whether uv and git are installed by running their --version commands.
For any tool that's missing, install it using the best method for my OS:
- Mac: prefer `brew install` (install Homebrew first if missing)
- Windows: prefer `winget install`
- Linux: prefer `apt install` or `dnf install`
Ask permission before each install command.
Do NOT install Node.js — we'll install it later only if needed.
When done, give me a summary of what's installed.
👉 Enter 키를 눌러 전송합니다.
🤖 에이전트 작업 확인, 팝업에서 허용 클릭
3단계 — 요약 읽기
에이전트가 완료되면 다음과 같이 표시됩니다.
✅ Setup complete:
- uv 0.4.18 ✅ (installed)
- git 2.42.0 ✅ (already had it)
- Node.js: skipped (will install later if needed)
문제가 발생한 경우
✅ 체크포인트: 에이전트가 uv와 git이 모두 설치되어 있음을 확인합니다. 총 시간: 약 3~5분 (또는 Mac에 Homebrew를 먼저 설치해야 하는 경우 약 7분)
프로젝트 클론
1단계: 이번 주 프로젝트 선택
Coding Jam은 매주 다른 미니 프로젝트가 진행되는 8주 프로그램입니다. 진행자가 오늘 어떤 주차를 진행하는지 알려드릴 것입니다. 해당 행을 찾아 URL을 복사합니다.
주 | 프로젝트 | 저장소 URL |
1 | AI 헤어스타일 가상 체험 |
|
2 | AI 아바타 생성기 |
|
3 | 내 특별한 해 캘린더 |
|
4 | 냉장고에서 레시피로 |
|
5 | AI 무드병 |
|
6 | 원페이지 포트폴리오 |
|
7 | 맞춤형 광고 재개 |
|
8 | AI 캐릭터 채팅 |
|
2 — 시작 화면으로 돌아가기
'저장소 클론' 버튼을 사용하려면 실행 화면으로 돌아가야 합니다.
👉 Antigravity에서 원하는 프로젝트를 클론합니다. 1주차 클론의 예시를 참고하되 올바른 저장소를 입력해야 합니다.
📝 참조 프롬프트
Git clone ⚠️ PASTE_YOUR_PROJECT and save to my local folder: ⚠️ PASTE_YOUR_PROJECT
3 — 프로젝트 둘러보기
파일 목록을 확인합니다. 다음과 같이 표시됩니다.
파일 / 폴더 | 어떤 기능인가요? |
BRIEF.md | 제품 아이디어: 빌드할 항목을 영어로 설명 |
reference/ | 작동하는 예시 앱이 포함된 폴더. AI가 코드를 작성할 때 이를 읽으므로 앱이 패턴과 일치합니다. |
.gitignore | Git에서 무시해야 하는 파일 목록 (기술적 — 무시) |
👉 클릭
BRIEF.md을 열어 프로젝트 아이디어를 확인하세요.
✅ 체크포인트: 프로젝트를 클론하고 작업공간으로 열었으며 BRIEF.md를 읽었습니다.
3. 워크숍 스킬 설치
'기능'은 GitHub에 저장된 일련의 명령어로서 AI에 전달할 수 있습니다.
1단계: Antigravity에 스킬 설치 요청
📝 채팅에 다음 프롬프트를 붙여넣습니다.
Please install the workshop skills into this workspace's .agent/skills/
folder. Run these two git clones from the project root:
1. git clone https://github.com/cuppibla/skills-garden .agent/skills/skills-garden
2. git clone https://github.com/google-gemini/gemini-skills .agent/skills/gemini-skills
When Antigravity asks permission to run each command, I'll click Allow.
When done, list the skills that are now available in this workspace.
2단계: 두 개의 팝업에서 '허용' 클릭
🤖 다음과 같이 표시됩니다.
I'll create the .agent/skills/ folder and clone both repos into it.
Running: git clone https://github.com/cuppibla/skills-garden .agent/skills/skills-garden
상담사가 프롬프트를 표시하는 경우 모든 작업을 허용합니다.
👉 파일 목록을 확인합니다. 이제 새 .agent/ 폴더가 표시됩니다. 클릭하여 펼치고 이 폴더에 skills-garden, gemini-skills과 같은 여러 스킬이 있는지 확인합니다.
각 스킬의 기능 (참고용, 조치 필요 없음)
기술 | 기능 |
| 제품 설계 문서 작성 |
| UX 디자인 문서 작성 |
| 엔지니어링 설계 문서 작성 (테스트 전략 섹션 포함) |
| 테스트를 작성하고 실행하며 실패를 자동 수정합니다 (최대 3회 시도). |
| 공식 Google 스킬 - Gemini API를 올바르게 사용하는 방법 |
| 공식 기능을 사용할 수 없는 경우 더 간단한 백업 |
| 시각적 스타일 참조 |
✅ 체크포인트: 파일 목록에 skills-garden/과 gemini-skills/이 모두 포함된 새 .agent/skills/ 폴더가 표시됩니다.
4. 사양 토크
Spec Talk는 AI에게 빌드하려는 내용을 말하는 2분 길이의 대화입니다. 아직 코드도 문서도 빌드된 것도 없습니다. 이야기를 나누는 것뿐입니다.
필수 질문 1개
AI가 알아야 할 가장 중요한 사항:
'무엇이 들어가고 무엇이 나오나요?'
🎯 모델: Gemini 3 Flash (기본값) - 간단한 Q&A
📝 다음 내용을 붙여넣습니다.
Here's what's in @BRIEF.md. Before we lock the spec, ask me 3 short
questions to refine it:
1. What's the one input I want the user to provide?
2. What's the magical moment for the user?
3. What are we deliberately NOT building (to keep scope tight)?
DO NOT generate any plans, docs, or code yet. Just ask me the questions
and wait for my answers.
🤖 AI와 대화하며 계획 다듬기
아직 문서를 생성하지 마세요
사양 설명이 끝날 때까지 에이전트가 파일을 생성해서는 안 됩니다. product.md 또는 기타 새 파일이 표시되면 에이전트에게 다음과 같이 말합니다. '중지해 줘. 방금 만든 문서를 삭제해 줘. 아직 사양 논의 단계에 있습니다.'
팁
✅ 체크포인트: 제품 아이디어에 관해 Antigravity와 간단한 대화를 나눴으며 Antigravity가 입력과 출력을 이해합니다. 아직 생성된 파일이 없습니다.
5. 디자인 문서 3개 생성
이제 코드가 실행되기 전에 AI가 세 가지 계획을 종이에 작성합니다. 세 가지 디자인 문서 기술을 순서대로 사용하여 하나의 프롬프트로 세 가지 작업을 모두 수행합니다.
3개의 문서
파일 | 포함된 제품 | 사용된 스킬 |
product.md | 사용자, 해결하려는 문제, 기능 |
|
ui.md | 화면 모양, 색상, 글꼴, 레이아웃 |
|
engineering.md | 기술 스택, 파일 구조, + 테스트 전략 섹션 |
|
1단계 - 세 문서를 한 번에 생성
🤖 사고량이 적은 Gemini 3.1 Pro로 전환 (권장)
📝 다음 프롬프트를 붙여넣으세요. 하나의 프롬프트로 세 가지 작업을 모두 수행할 수 있습니다.
Apply all three design-doc skills in this order:
1. pm-design-doc from .agent/skills/skills-garden/design-doc-skills/pm-design-doc/
→ Generates product.md
2. ux-design-doc from .agent/skills/skills-garden/design-doc-skills/ux-design-doc/
→ Generates ui.md (based on the product.md you just created)
3. eng-design-doc from .agent/skills/skills-garden/design-doc-skills/eng-design-doc/
→ Generates engineering.md (based on product.md, ui.md, and @BRIEF.md)
→ MUST include a "Testing strategy" section with real content
(specific functions to unit-test, one integration test per major flow,
and what's deliberately NOT being tested)
Use the patterns in @reference/ as guidance for the engineering doc
(but vary if the brief justifies it).
Save all three files in the project root. After each one is saved,
briefly confirm what you saved before moving to the next.
When all three are done, give me a final summary listing the section
titles in each file.
2단계: 저장된 파일 확인
👉 파일 목록을 확인합니다. 이제 이전에 있던 항목 외에 다음 항목이 표시됩니다.
codingjam-week-1/
├── product.md ← NEW
├── ui.md ← NEW
├── engineering.md ← NEW
├── BRIEF.md
├── reference/
└── .agent/
3단계 - 검토 및 반복
결정은 여러분이 내리세요. AI가 계획을 작성했습니다. 이제 이를 읽고 변경을 요청합니다.
가장 중요한 습관
변경이 필요한 경우 코드가 아닌 문서를 변경하세요. 문서가 정보 소스입니다.
🤖 세 가지 문서를 모두 읽고 검토하세요
👉 각 파일을 위에서 아래로 엽니다 (파일 목록에서 클릭).
product.md— 원하는 내용이 맞나요?ui.md- 화면과 디자인이 올바른가요?engineering.md- 테스트 전략이 적절한가요? (기술을 이해할 필요는 없습니다. 계획이 있는지 확인하기만 하면 됩니다.)
🤖 이제 문서가 준비되었으므로 다음 단계로 이동하세요.
6. 구현 + 테스트
Codelab에서 가장 큰 섹션입니다. AI는 세 문서를 가져와 앱을 빌드합니다. 코드와 테스트를 한 번에 함께 빌드합니다. 이 섹션이 끝나면 자체 테스트를 통과하는 작동하는 코드베이스가 생성됩니다.
코드와 테스트를 함께 사용하는 이유
engineering.md는 이미 어떤 테스트가 있어야 하는지 지정합니다 (테스트 전략 섹션). 이러한 테스트를 통과해야 구현이 완료됩니다. 따라서 한 단계에서 두 가지 작업을 모두 수행합니다.
🤖 사고력이 높은 Gemini 3.1 Pro로 전환 (권장)
1단계: AI에 코드와 테스트 빌드 요청
📝 다음 내용을 붙여넣습니다.
You're going to do two things in one shot.
PART 1 — IMPLEMENT THE APP CODE
- Build it according to @engineering.md (stack, file structure)
- Match the UI described in @ui.md
- Use the patterns in @reference/ as guidance for code style
- Backend: use Python with `uv` for dependency management
- If your chosen stack requires Node.js and it isn't installed on my
system, install it via Antigravity (use brew/winget/apt) — ask
permission first
- DO NOT start any dev servers — that's a later section
PART 2 — APPLY THE TEST-GATE SKILL
After the code is written, apply the test-driven-dev skill from
.agent/skills/skills-garden/eng-skills/test-driven-dev.md.
Use the "Testing strategy" section in @engineering.md as the test plan.
IMPORTANT: Mock the Gemini API calls in tests — use a stub that returns
fake response data. The real API key isn't set up yet, and tests should
be deterministic and free anyway (best practice).
The skill should:
1. Write the tests described in the Testing strategy
2. Run them (use pytest for Python, Vitest or Jest for JS)
3. If any fail, fix the CODE (not the tests) and re-run
4. Up to 3 retry attempts max
5. If still failing after 3 tries, STOP and tell me what's broken
When Antigravity asks permission to run commands (uv sync, uv pip
install, pytest, etc.), click Allow.
Report results when both parts are done.
🤖 팝업에서 허용 클릭 (여러 개)
2단계: 최종 보고서 읽기
완료되면 다음을 확인합니다.
- ✅ 코드가 포함된
backend/폴더가 있음 - ✅ 코드가 포함된
frontend/폴더가 있음 - ✅ 테스트 파일이 포함된
tests/폴더가 있음 - ✅ 요약에 '모든 테스트 통과'라고 표시됩니다('3회 재시도 후 실패'가 아님).
- ✅ 에이전트가 서버를 시작하지 않음
3번의 테스트 재시도가 모두 실패하면 어떻게 되나요?
드물지만 가능합니다. 일반적으로 엔지니어링 문서의 테스트 전략이 빌드된 항목에 비해 비현실적이라는 의미입니다.
📝 다음 내용을 붙여넣습니다.
The auto-fix loop hit the 3-try cap. Pull up @engineering.md and look
at the Testing strategy section. Is the strategy realistic for what
got built? Suggest updates to the doc so the tests align with reality.
Don't change the code yet — update the doc, then re-apply the
test-driven-dev skill.
이상한 점이 발견되면 어떻게 해야 하나요?
👉 AI가 문서와 일치하지 않는 항목을 빌드한 경우 문서로 돌아가세요. AI에 '코드를 수정'해 달라고 요청하지 마세요.
예:
I see you built the chat as a popup, but @ui.md says it should be a
full page. Either update ui.md if a popup is actually better, OR
rebuild the chat as a full page to match the current ui.md.
항상: 문서가 정보 소스입니다.
✅ 체크포인트: 코드가 있고, 테스트가 있고, 테스트가 통과됩니다. API 키를 설정할 준비가 되었습니다.
7. Google Cloud + API 키 설정
1단계: AI Studio에서 Gemini API 키 가져오기 (1분)
- 새 브라우저 탭에서 https://aistudio.google.com/app/apikey를 엽니다.
- 동일한 Google 계정으로 로그인합니다.
- API 키 만들기 (오른쪽 상단)를 클릭합니다.
- 프로젝트 드롭다운이 포함된 대화상자가 열립니다.
- 이전에 Google 프로젝트를 만든 적이 있는 경우 프로젝트를 선택하고 '기존 프로젝트에서 API 키 만들기'를 클릭합니다.
- 목록에 없는 경우: '프로젝트 만들기'를 클릭합니다.
- 표시되는 API 키를 복사합니다.
AIza...로 시작하며 길이는 약 40자입니다.
✏️ 안전한 곳에 붙여넣습니다. 다음 단계에서 Antigravity에 제공할 예정입니다.
2단계 — Antigravity에 .env 설정 요청 (30초)
Antigravity로 돌아가 채팅을 엽니다.
⚠️ 중지하세요. 붙여넣기 전에 읽어보세요.
아래 프롬프트에는 PASTE_YOUR_API_KEY_HERE 및 PASTE_YOUR_PROJECT_ID_HERE 자리표시자가 포함되어 있습니다.
1단계의 실제 값으로 바꿔야 .env 파일에 ⚠️ PASTE_... 텍스트가 포함되지 않고 앱이 작동합니다(MUST).
보내기를 클릭하기 전에 프롬프트를 스캔하여 다음이 표시되는지 확인합니다.
GEMINI_API_KEY=AIzaSy...(AIzaSy로 시작, 영문 기준 약 40자)
그래도
⚠️ PASTE_...
프롬프트의 아무 곳에나 입력하고 아직 전송하지 마세요. 먼저 대체해야 합니다.
📝 붙여넣기 프롬프트 (
⚠️ PASTE_...
마커를 먼저 추가하세요.
Apply the gemini-api-dev skill from .agent/skills/gemini-skills/skills/gemini-api-dev/.
(If that skill isn't found, fall back to .agent/skills/skills-garden/eng-skills/gemini-api.md)
Create a .env file in the backend folder with these settings:
- GEMINI_API_KEY= ⚠️ PASTE_YOUR_API_KEY_HERE
- Any other env vars the app needs based on @engineering.md
Also verify:
- .env is in .gitignore so the key never gets committed
- The backend code reads GEMINI_API_KEY at startup
- The Gemini SDK is initialized correctly (use google-genai for Python)
When Antigravity asks permission to install Python packages, click Allow.
When done, show me the .env contents with the KEY redacted (just first 6 chars + ...).
🤖 예상: 에이전트가 .env를 만들고, google-genai을 설치하고 (사용자가 허용 클릭), 수정된 키로 확인합니다.
✅ .env created at backend/.env
GEMINI_API_KEY=AIzaSy... (40 chars, redacted)
.env is already in .gitignore ✓
Backend reads GEMINI_API_KEY via os.getenv() ✓
Gemini client initialized ✓
8. 미리보기 및 확인
코드가 빌드됩니다. 테스트를 통과합니다. API 키가 구성되었습니다. 이제 앱을 열고 여기저기 클릭해 보세요.
테스트에서 놓치는 인간의 발견
테스트 캐치 | Humans Catch |
잘못된 반환 값 | 보기 흉한 색상 |
함수 호출이 중단됨 | 혼동을 야기하는 문구 |
가져오기가 누락됨 | 이상한 위치에 있는 버튼 |
off-by-one 오류 | 애니메이션이 버벅거림 |
논리 버그 | 바이브가 꺼져 있습니다 |
1단계: Antigravity에 개발 서버 시작 요청
🎯 모델: 기본값 (플래시)이 적합합니다.
📝 다음 내용을 붙여넣습니다.
Please start the dev server(s) so I can preview the app in my browser.
Tell me the URL when it's ready. When Antigravity asks permission to
run the server command, I'll click Allow.
🔔 팝업: uv run uvicorn main:app --reload (또는 유사한 팝업) → 허용 클릭
2단계 - 미리보기 URL 열기
🤖 상담사는 다음과 같이 보고합니다.
Backend running at: http://localhost:8000
Frontend served at: http://localhost:8000 (backend serves it)
URL은 일반적으로 http://localhost:8000 또는 http://localhost:5173입니다.
👉 채팅에서 URL을 클릭하거나 새 브라우저 탭에 복사하여 붙여넣습니다.
3단계: 둘러보기
실제 사용자가 하는 것처럼 사용합니다.
- 모든 버튼 클릭
- 내용 입력
- 항목 위로 마우스를 가져가기
- 처음부터 끝까지 기본 흐름 시도
모든 것이 올바르게 표시되면 9.7단계 (README 작성)로 건너뜁니다. 9.4~9.6단계는 문제가 발견된 경우에만 필요합니다.
4단계 — README 작성
앱이 작동하면 다음과 같이 잠급니다.
📝 다음 내용을 붙여넣습니다.
The app works! Please create a README.md in the project root that explains:
- What this app does (in plain English)
- How to install it on a new machine (uv sync, etc.)
- How to run the dev server(s)
- The 3 design docs (@product.md, @ui.md, @engineering.md) are the
source of truth — anyone can read them to understand the system
Save it as README.md.
🤖 예상: README.md이 파일 목록에 표시됩니다.
README가 중요한 이유
✅ 체크포인트: 앱을 클릭하여 둘러보고, 문제가 있으면 해결하고, 리드미를 저장했습니다.
9. 🎉 MVP를 출시했습니다.
수고하셨습니다.
빌드한 항목
- ✅ AI 기반 웹 앱
- ✅ 설계 문서 3개 (
product.md,ui.md,engineering.md) - ✅ 코드를 변경할 때마다 실행되는 실제 테스트 모음
- ✅ 언제든지 돌아올 수 있도록
README.md - ✅ Google의 Gemini AI에 연결
아이디어에서 작동하는 앱으로 전환하는 과정에서 직접 코드를 한 줄도 작성하지 않았습니다. 정말 대단하네요.
학습한 내용
기술 | 중요한 이유 |
사양 → 코드+테스트 → 확인 | 먼저 계획을 세우세요. 코드와 테스트를 함께 빌드합니다. 마지막으로 클릭합니다. 항상 이 순서대로입니다. |
코드가 아닌 문서를 수정하세요 | 사용 중지된 항목이 있으면 요금제를 변경하고 다시 빌드하세요. 패치를 적용하지 않습니다. |
안전 게이트로 테스트 | 구현에 내장됨: AI가 사용자가 직접 처리하기 전에 어리석은 문제를 포착합니다. |
회귀 규칙 | 사람이 발견한 모든 버그는 테스트가 됩니다. 버그가 다시 발생하지 않습니다. |
문서 기반 피벗 | 방향이 바뀌면 문서를 변경하세요. 나머지는 AI가 처리합니다. |
Antigravity 3레이어 흐름 | 채팅에서 영어로 입력 → 에이전트가 명령어를 선택 → 사용자가 승인 |
다음 주에 다시 오시나요?
- 8주 표에서 다른 행 선택
- Antigravity의 '저장소 클론' 버튼을 통해 해당 주의 저장소를 클론합니다.
- 스킬은 작업공간별로 새로 설치됩니다 (작업공간 범위 = 남은 상태 없음).
- 동일한 Google Cloud 프로젝트를 재사용할 수 있습니다.
- 그 외에는 방금 배운 것과 동일한 워크플로입니다.
다음 단계
- 프로젝트 게시: 코딩 잼 사이트에서 프로젝트를 게시하세요.
- 집에서 빌드: 세 개의 문서를 휴대할 수 있습니다. AI 도구에서 열고 계속 빌드하세요.
- 친구 데려오기: 이 Codelab을 통해 새로운 사람과 페어링합니다. 가장 빠르게 배우는 방법은 가르치는 것입니다.