00. Setup

Spirit of Kiro 게임의 클라이언트와 서버를 로컬에서 띄우고 AWS 계정과 연결하여, Kiro로 작성한 변경 사항을 바로 확인할 수 있도록 개발 환경을 준비합니다.

로컬 개발 환경 구성

이 가이드는 오픈 소스 게임 Spirit of Kiro를 직접 실행해 보면서 Kiro의 워크플로우를 익히는 시리즈의 첫 단계입니다. 아래 절차를 따라가면 컨테이너 기반의 풀 스택 환경을 손쉽게 띄울 수 있습니다.

1. 저장소 클론

먼저 GitHub에서 코드를 가져오고 워크숍용 challenge 브랜치로 이동합니다.

git clone git@github.com:kirodotdev/spirit-of-kiro.git
cd spirit-of-kiro/
git checkout challenge

아키텍처를 큰 그림에서 이해하고 싶다면 저장소의 docs/architecture.md를, 컴포넌트들이 어떻게 맞물리는지 자세히 보고 싶다면 docs/appsec-overview.md를 먼저 살펴보면 좋습니다.

2. 사전 요구사항

컨테이너 런타임: Docker Desktop 또는 Podman (이 가이드에서는 Podman을 권장합니다)
AWS 계정과 AWS CLI 설치, 그리고 자격 증명 설정 완료
다음 모델 중 하나 이상에 대한 Amazon Bedrock 액세스 권한
- Amazon Nova Pro
- Anthropic Claude Sonnet 3.7
- Anthropic Claude Sonnet 4

3. 의존성 점검

준비된 환경이 요구사항을 충족하는지 스크립트로 한 번에 확인합니다.

./scripts/check-dependencies.sh

check-dependencies.sh 실행 화면 — 의존성 검사 스크립트가 필요한 도구와 AWS 설정을 확인합니다.

4. Cognito 사용자 풀 배포

플레이어 계정을 관리할 Amazon Cognito 사용자 풀을 배포합니다. AWS Free Tier에서도 운영할 수 있습니다.

./scripts/deploy-cognito.sh game-auth

Tip. game-auth 인자는 CloudFormation 스택 이름으로 사용됩니다. 원하는 다른 이름으로 바꿔도 됩니다.

Cognito 배포 진행 화면 — CloudFormation을 통해 Cognito 사용자 풀이 생성되는 모습.

5. 빌드와 실행

이제 컨테이너를 빌드하고 스택을 띄웁니다. 변경 사항을 자동으로 반영하기 위해 --watch 옵션을 사용합니다.

podman compose build && podman compose up \
  --watch \
  --remove-orphans \
  --timeout 0 \
  --force-recreate

처음 실행할 때는 이미지를 받아오느라 몇 분이 걸릴 수 있지만 이후에는 훨씬 빠르게 기동됩니다. 스택을 멈추려면 터미널에서 Control + C (macOS는 Command + C)를 누르세요.

Podman을 처음 쓰나요? 가상 머신이 한 번도 초기화된 적이 없다면 podman machine init && podman machine start를 먼저 실행해야 합니다.

주의. Podman 가상 머신은 호스트가 절전 모드에 들어갔다 나오면 시간이 어긋나서 AWS 호출이 실패할 수 있습니다. 이럴 때는 다음 명령으로 시간 동기화를 다시 맞춰 주세요.

podman machine ssh sudo systemctl restart chronyd.service

빌드 및 실행 과정 — compose 빌드와 실행이 동시에 진행되는 모습.

Podman UI에 표시된 컨테이너 목록 — 스택이 정상 기동되면 Podman UI에서 실행 중인 컨테이너를 확인할 수 있습니다.

6. 데이터베이스 부트스트랩

로컬 스택은 DynamoDB Local 컨테이너를 사용합니다. 게임이 동작하려면 필요한 테이블을 미리 생성해 두어야 합니다. 스택이 떠 있는 상태에서 새 터미널을 열고 다음을 실행하세요.

podman exec server mkdir -p /app/server/iac && \
podman cp scripts/bootstrap-local-dynamodb.js server:/app/ && \
podman cp server/iac/dynamodb.yml server:/app/server/iac/ && \
podman exec server bun run /app/bootstrap-local-dynamodb.js

DynamoDB 테이블 생성 — 스크립트가 로컬 DynamoDB에 필요한 테이블을 만들어 줍니다.

데이터 초기화. DynamoDB Local 데이터는 docker/dynamodb/shared-local-instance.db 파일로 보존됩니다. 처음 상태로 되돌리려면 이 파일을 삭제하고 스택을 재시작한 뒤 위 부트스트랩 명령을 다시 실행하면 됩니다.

7. 동작 확인

서버가 살아 있는지 확인합니다. curl localhost:8080을 실행하면 OK가 응답으로 와야 합니다.
브라우저에서 localhost:5173을 열어 클라이언트에 접속합니다.
계정을 새로 만든 뒤 게임을 시작해 보세요.

게임 플레이 가이드

본격적으로 코드를 고치기 전에 게임 메커닉을 익혀 두면 이후 실습이 훨씬 수월합니다.

이동·상호작용: WASD로 이동, E로 상호작용, T로 들고 있는 아이템을 던지기
PULL lever: 빨간 레버를 당기면 임의의 아이템이 등장합니다.
아이템: E로 줍고, 아래쪽 문을 향해 던질 수 있습니다.
Workbench: 작업대에 아이템을 올린 뒤 뒷벽의 도구와 앞쪽 작업 영역 사이를 드래그할 수 있습니다. 도구를 클릭해 선택한 대상에 "quirk"를 부여하면 도구와 대상이 함께 변형됩니다. 조합의 가짓수가 매우 많으니 자유롭게 실험해 보세요.
Overflow: 아이템을 부수면 바닥으로 흘러넘칠 수 있습니다. 가끔 정리하는 편이 좋습니다.
Chest: 여분의 아이템을 보관하는 저장소입니다.
Shop keeper: 아래 문으로 던진 아이템은 상인이 감정해 보상을 줍니다. 재미있고 독특하며 상태가 좋고 희귀해 보이는 아이템일수록 높은 평가를 받습니다.
Computer: 자신과 다른 플레이어가 버리거나 감정한 아이템 목록이 보입니다. 다른 플레이어의 아이템을 사거나 잃어버린 아이템을 되찾는 무작위 상점처럼 동작합니다.